About projects

A project represents a logical unit of functionality whose boundaries are up to you. Your app can contain one or more projects. The directory structure of a project triggers how the deployer finds and labels packages and actions, how it deploys static web content, and what it ignores. In more complex cases you can set more control over project deployment by adding a project configuration.

Project directory structure

A project has a fixed directory structure, which determines how projects are deployed. Here’s a diagram that summarizes the directory structure of an individual project with no project configuration, with explanation below.

Figure 2: Basic directory structure of a project

The project has a root directory, within which a certain small number of directory names are significant to the deployer, specifically:

  • A packages directory. Each subdirectory of packages is treated as a package and is assumed to contain actions, in the form of either files or directories. Files in the packages directory are ignored by the deployer.
  • A web directory, which contains directories and files with static web content.

Anything else in the root directory is ignored by the deployer, shown in blue in the diagram. This lets you store things in the root directory that need to be “off to the side,” such as build directories used by the deployer and project documentation.

Projects with multiple actions

Adding more actions to a project is easy when each action is related to a single source code file. You can create as many subdirectories of the packages directory as you want and add as many source code files as you want to each subdirectory.

Factors in choosing project size

There is no limit on how many packages and actions can be in a project. However, using fewer very large projects or many small projects both have some negative ramifications, which are solved by using incremental deployment.

For example, you could create one large project. However, the default behavior of the deployer is to deploy everything in the project that it can, so deployment could become time-consuming.

The other extreme is to create many small projects. You can use the project deploy command with a list of projects in a single invocation to deploy them all at once (e.g., nim project deploy example1 example2 …). Having lots of small projects may lengthen the build process, especially during iterative development.

Incremental deployment facilitates deployment of both large and small projects, so you can create projects that make sense logically.

Factors in choosing project boundaries

Projects and actions are very flexible.

  • When deploying a project, all of its actions and web resources are installed into a single target namespace.
  • Multiple projects can deploy into the same namespace.
  • The actions within a project can span multiple packages and a given package can have actions contributed by multiple projects.

In other words, you decide on project boundaries based on deployment convenience.

Note: As a consequence of this flexibility, it’s important to watch for possible collisions between different projects trying to install the same resource. There are some audit trails that can help, described in Deployer recordkeeping.