Quick Start

This guide gets you from zero to a running NNO platform console in under 10 minutes. By the end you will have a local dev server connected to NNO'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 NNO CLI

pnpm add -g @neutrino-io/cli

Verify the install:

nno --version

The CLI provides three main namespaces: nno project for local dev and deployment, nno feature for scaffolding feature packages, and nno marketplace for browsing the feature catalogue.

Step 2 — Log in

nno login

This opens a browser window to authenticate with NNO. 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

nno project init my-app

This command:

1. Creates a new GitHub repository from the nno-stack-starter template under your organization
2. Clones it locally into ./my-app/
3. Registers a new Platform in the NNO Registry and returns your PLATFORM_ID
4. Writes a .env.local with the correct VITE_GATEWAY_URL, VITE_AUTH_URL, and VITE_PLATFORM_ID values for your new platform

my-app/
├── apps/console/          # React 19 shell — deploys to CF Pages
├── src/config/
│   ├── features.config.ts # Feature registry config
│   └── features.overrides.ts
├── .env.example
└── .env.local             # Written by nno project init (gitignored)

Install dependencies after the clone completes:

cd my-app
pnpm install

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 NNO authentication screen appears. Sign in with your NNO 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

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 NNO platform. Here is where to go next:

• Platform Setup 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