Skip to content

Project structure

As you have seen in the Quickstart tutorial, pavex new is a quick way to scaffold a new project and start working on it. If you execute

pavex new demo

the CLI will create a project with the following structure:

app/
configuration/
server/
server_sdk/
workspace_hack/
Cargo.toml
CONFIGURATION.md
deny.toml
Dockerfile
README.md
rust-toolchain.toml

What is the purpose of all those folders? Why is cargo-px needed to build a Pavex project? Are there any conventions to follow?

This guide will answer all these questions and more.

Summary

If you're in a hurry, here's a quick summary of the most important points:

  • A Pavex project is a Cargo workspace with at least three crates:
  • a core crate (library), conventionally named app
  • a server SDK crate (library), conventionally named server_sdk
  • a server crate (binary), conventionally named server
  • The app crate contains the Blueprint for your API. It's where you'll spend most of your time.
  • The server_sdk crate is generated from the core crate by pavex generate, which is invoked automatically by cargo-px when building or running the project.
    You'll never modify server_sdk manually.
  • The server crate is the entrypoint for your application. You'll have to change it whenever the application state changes or if you want to tweak the binary entrypoint (e.g. modify the default telemetry setup). Your integration tests live in this crate.

Using the demo project as an example, the relationship between the project crates can be visualised as follows:

If you want to know more, read on!