Project structure

This page describes what Shuttle expects from your project structure, how it handles cargo workspaces, and how to use a custom binary name.

​

Basic structure

After initializing a basic Shuttle project, the file structure will look like this:

.
├── .gitignore
├── Cargo.toml
├── Shuttle.toml      (optional)
└── src/
    └── main.rs

The file Shuttle.toml is optional and can be used to override default settings for project name and deployment files.

​

Workspaces

Shuttle supports cargo workspaces. Simply run the project and deployment commands in the root of the workspace, and the project name will be taken from the directory name of the workspace or a Shuttle.toml with a name key in the root of the workspace. See Project Name for more info.

This is an example of a workspace structure with shared code between a backend and frontend crate:

.
├── .gitignore
├── Cargo.toml
├── Shuttle.toml      (optional)
├── backend
│   ├── Cargo.toml
│   └── src
│       └── main.rs   (contains #[shuttle_runtime::main])
├── frontend
│   ├── Cargo.toml
│   └── src
│       └── main.rs
└── shared
    ├── Cargo.toml
    └── src
        └── lib.rs

​

Caveats

We currently only support one Shuttle service per workspace, so you can have many crates in a workspace, but only one crate with a shuttle_runtime::main macro. We intend to allow starting several Shuttle services at the same time, as part of the same project. The long term plan is to have one central service that routes to the other services in the project, sharing resources amongst them. Any feedback on what you would like to see in this area is most welcome.

​

Cargo feature flags

Shuttle does not allow explicitly setting feature flags (yet), but instead activates the feature shuttle if it exists (along with disabling default features).

# Compiling this package on Shuttle will enable the features
# "shuttle" and "bar". To use default features on Shuttle, add
# "default" to the shuttle array.
[features]
default = ["foo"]
shuttle = ["bar"]
foo = []
bar = []

​

Multiple binaries

If you want to keep your project structured for allowing both running with and without Shuttle, check out the standalone-binary example. This is great for gradually adding Shuttle into your project.