CLI and Configuration

Natrix comes with a powerful CLI that helps you create, develop, and build your applications. This page explains all the available commands and configuration options.

The Natrix CLI

The Natrix CLI is a set of tools designed to make working with Natrix projects as smooth as possible. It handles everything from project creation to development servers with hot reloading and optimized production builds.

Creating New Projects

The new command creates a brand new Natrix project with all the necessary files and configuration set up for you.

natrix new my-awesome-app

tip

By default, new projects use nightly Rust for better optimizations and smaller binaries. If you prefer to use stable Rust instead, add the --stable flag:

natrix new my-awesome-app --stable

This command creates a new project directory with the following structure:

my-awesome-app/
├── Cargo.toml
├── .gitignore
├── rust-toolchain.toml
└── src/
    └── main.rs

Development Server

The dev command starts a local development server with live reloading.

natrix dev

Building for Production

When you're ready to deploy your app, use the build command to create an optimized production build.

natrix build

Configuration

Natrix can be configured through your project's Cargo.toml file. Add a [package.metadata.natrix] section to customize how Natrix builds your application.

[!IMPORTANT] These options only take affect for production builds. For dev all these settings have sensible defaults.

Cache Busting

Control how asset URLs are versioned to ensure browsers load the latest versions:

[package.metadata.natrix]
cache_bust = "content"  # Options: "none", "content", "timestamp"

content: (Default) Creates a hash based on the file content
timestamp: Creates a hash based on the current build time
none: Doesn't add any cache busting

tip

Content-based cache busting is recommended for production as it only changes URLs when the content actually changes, maximizing cache efficiency.

Base Path

If your app isn't hosted at the root of a domain, you can specify a base path prefix:

[package.metadata.natrix]
base_path = "/my-app"

This configures all asset URLs to be prefixed with the specified path.

important

Always include a leading slash in your base_path value.

SSG

By default natrix extracts metadata from your application, importantly for this to work your application must call mount, and should not access any browser apis before or after it. If your application does not use mount you should set this option to false.

This will force css to be injected at runtime instead, and more importantly will not attempt to build and call your binary during bundling.

[package.metadata.natrix]
ssg = false # Default: True

for example if you are doing something like this you need to set ssg = false

fn main() {
    let document = web_sys::window().unwrap(); // This will fail during ssg
    // ...
}

Keyboard shortcuts

Natrix