Quick Start

This guide gets you from zero to a running Neutrino platform console in under 10 minutes. By the end you will have a local dev server connected to Neutrino's backend and a deployment on Cloudflare Pages.

Prerequisites

Before you start, make sure you have the following:

• Node.js 20+ — check with node --version
• pnpm 10+ — install via npm install -g pnpm if needed
• A Cloudflare account — free tier works for development
• Wrangler CLI — npm install -g wrangler, then wrangler login
• A GitHub Personal Access Token (PAT) with read:packages scope — required to install @neutrino-io/* packages from GitHub Packages

Configure package registry access

@neutrino-io/* packages are hosted on GitHub Packages. Export your PAT before installing:

export GITHUB_TOKEN=ghp_YOUR_TOKEN

Add this to your shell profile (~/.zshrc or ~/.bashrc) to persist it across sessions.

Your project's .npmrc (included in the starter) points the @neutrino-io scope at npm.pkg.github.com and reads ${GITHUB_TOKEN} automatically. Do not hardcode your token in .npmrc.

Step 1 — Install the Neutrino CLI

pnpm add -g @neutrino-io/cli

Verify the install:

nno --version

The CLI provides five namespaces: nno project (local dev and deployment), nno feature (feature scaffolding), nno doctor (environment diagnostics), nno setup (platform provisioning wizard), and nno platform (platform management).

Step 2 — Log in

nno login

This opens a browser window to authenticate with Neutrino. After completing the flow your credentials are stored locally and all subsequent nno commands are authenticated.

To check who you are logged in as at any time:

nno whoami

Step 3 — Create a project

Create a directory for your project and run the nno setup wizard:

mkdir my-app && cd my-app
nno setup

The interactive wizard:

1. Authenticates your session (if not already logged in)
2. Registers a new Platform in the Neutrino Registry and returns your PLATFORM_ID
3. Provisions the required Cloudflare resources for your platform
4. Writes a .env.local with VITE_GATEWAY_URL, VITE_AUTH_URL, and VITE_PLATFORM_ID populated for your new platform

After the wizard completes, install dependencies:

pnpm install

Planned: A nno project init command and a starter template repo (nno-stack-starter) that scaffolds the full project structure in one step are tracked as future feature work.

Step 4 — Start dev

pnpm dev

The console shell starts at http://localhost:5173.

What happens at startup:

1. Vite runs the neutrino-feature-discovery plugin, which scans your package.json for all @neutrino-io/feature-* dependencies and generates the virtual:feature-registry module.
2. The shell boots and loads enabled features from features.config.ts. Routes and sidebar entries are built statically — no network round-trips at startup.
3. The Neutrino authentication screen appears. Sign in with your Neutrino credentials.

If no sidebar items appear after sign-in, check that at least one feature has enabled: true in src/config/features.overrides.ts:

// src/config/features.overrides.ts
export const featureOverrides = {
  settings: {
    enabled: true,
  },
};

Restart pnpm dev after changing this file.

Step 5 — Deploy

When you are ready to ship, deploy to Cloudflare Pages:

nno project deploy <platform-id>

Replace <platform-id> with the 10-character platform ID assigned during nno setup (also stored in .env.local as VITE_PLATFORM_ID).

This command triggers a CI build via GitHub Actions, which runs pnpm build and then wrangler pages deploy. The first build takes 2–3 minutes.

Before deploying for the first time, add the following to your Cloudflare Pages project's environment variables (Settings → Environment variables):

You also need a PACKAGE_READ_TOKEN repository secret for GitHub Actions:

Repository → Settings → Secrets and variables → Actions → New repository secret
Name:  PACKAGE_READ_TOKEN
Value: PAT with read:packages scope

Once the deployment succeeds, your console is live at the Cloudflare Pages URL shown in the dashboard.

Troubleshooting

Next Steps

You have a running Neutrino platform. Here is where to go next:

• Environments Guide — configure multiple environments, custom domains, and DNS
• Feature Development — build a custom feature package with routes, sidebar navigation, and the featureManifest export
• Stacks — group features together with shared Cloudflare resources (D1, R2, KV)
• Authentication — understand how Better Auth integrates with your platform's auth Worker
• Multi-Environment Guide — manage .env files for local, staging, and production