Installation

To build your first application, follow the Quickstart. Continue here for CLI launchers, scaffold flags, existing services, and recovery.

Requirements

• Go 1.26 or newer.
• Node.js 24 or newer is recommended. The generated admin also supports Node.js 20.19+ on the 20.x line and 22.12+ on the 22.x line.
• One supported package manager: npm, Bun, pnpm, or Yarn.
• PostgreSQL projects: Docker/OrbStack for the generated local service, or an existing PostgreSQL 17 database.
• MongoDB projects: Docker/OrbStack for the generated replica set, or an existing transaction-capable replica set. Production support is limited to the exact MongoDB profile.
• SQLite projects need no database service or Docker.

Choose npm, Bun, pnpm, Yarn, or the native Go command. The generated project records its package manager in ridu.toml.

Install the CLI

Choose the launcher you want the project to use:

npm create ridu@latest my-app

bun create ridu@latest my-app

pnpm create ridu@latest my-app

yarn create ridu my-app

The positional name sets the project directory. The wizard asks for the template, database, and optional coding-agent guidance; omit my-app when you want it to ask for the directory too.

To skip the JavaScript initializer, install the native command and open the wizard directly. The native path also asks which package manager the generated project should use:

go install github.com/riducms/ridu/cmd/ridu@latest
ridu new

Choose scaffold options

For a new named directory, the target must not already exist. To create a project in the current directory, use npm create ridu@latest . (or enter . in the wizard). Ridu prints a warning and preserves unrelated files, including an existing .git directory. If a scaffold-owned path such as README.md, .gitignore, admin, or content already exists, creation stops before adding any project files. Move conflicting paths aside or choose a new directory.

The wizard derives example.com/<project> and @<project> defaults from that directory, normalizing its name to lowercase kebab-case when using .. Supply --module and --scope when those import/package identities must match names already reserved by your organization.

Run any launcher without project options for the interactive wizard. Native ridu new also asks which package manager to use. Set RIDU_ACCESSIBLE=1 for stable plain-text prompts suitable for screen readers. Flags skip their matching prompts; use --no-agent to omit agent guidance.

ridu new \
  --template starter \
  --database postgres \
  --package-manager npm \
  --agent codex \
  --module github.com/acme/content \
  --scope @acme \
  content

The created project includes go.sum, its initial migration, and generated manifest, OpenAPI, Go, TypeScript, and admin plugin contracts.

Use the project-local CLI

New projects include @riducms/cli as a development dependency. Install the workspace, then use its scripts:

cd content
npm install
ridu version
npm run dev

cd content
bun install
ridu version
bun run dev

cd content
pnpm install
ridu version
pnpm run dev

cd content
yarn install
ridu version
yarn run dev

The dev script runs the API, selected development database, contract generation, and admin. dev:admin starts only Vite when another process already runs the API. Use the selected manager’s ridu script for doctor, generation, migrations, checks, builds, and plugins.

For existing generated projects, derive the npm launcher version from the framework already pinned in go.mod, then add the same scripts:

RIDU_VERSION="$(go list -m -f '{{.Version}}' github.com/riducms/ridu | sed 's/^v//')"
npm install --save-dev --save-exact "@riducms/cli@$RIDU_VERSION"

RIDU_VERSION="$(go list -m -f '{{.Version}}' github.com/riducms/ridu | sed 's/^v//')"
bun add --dev --exact "@riducms/cli@$RIDU_VERSION"

RIDU_VERSION="$(go list -m -f '{{.Version}}' github.com/riducms/ridu | sed 's/^v//')"
pnpm add --save-dev --save-exact "@riducms/cli@$RIDU_VERSION"

RIDU_VERSION="$(go list -m -f '{{.Version}}' github.com/riducms/ridu | sed 's/^v//')"
yarn add --dev --exact "@riducms/cli@$RIDU_VERSION"

Add the selected manager to ridu.toml. Existing version-1 projects that omit this key continue to use Bun for compatibility.

version = 1
database = "postgres"
package_manager = "npm"

Then add manager-neutral root scripts. Keep an existing dev:admin script, or use the manager-specific workspace command emitted by a new scaffold.

{
  "devDependencies": {
    "@riducms/cli": "X.Y.Z"
  },
  "scripts": {
    "dev": "ridu dev",
    "ridu": "ridu",
    "check": "ridu check",
    "build": "ridu build"
  }
}

Replace X.Y.Z with the value printed in RIDU_VERSION; do not leave the placeholder in the file. If you prefer a global command, install it with npm install --global @riducms/cli@latest or go install github.com/riducms/ridu/cmd/ridu@latest. Global commands can drift from older projects, so pin the project-local package for repeatable work and automation.

Open the admin

Run the selected manager’s dev script from the project directory and open the printed admin URL (normally http://localhost:8080/admin). PostgreSQL and MongoDB start their local services when needed; SQLite opens its local development file. On an empty auth collection, the admin shows one-time first-user setup.

The Quickstart continues from here with the first account, document, and generated SDK read.

Use an existing database service

For PostgreSQL or MongoDB, bind the URL to the command and tell development not to start Compose:

DATABASE_URL="$DEVELOPMENT_DATABASE_URL" npm run dev -- --no-docker

DATABASE_URL="$DEVELOPMENT_DATABASE_URL" bun run dev -- --no-docker

DATABASE_URL="$DEVELOPMENT_DATABASE_URL" pnpm run dev --no-docker

DATABASE_URL="$DEVELOPMENT_DATABASE_URL" yarn run dev --no-docker

Without an explicit MongoDB URL, development uses mongodb://127.0.0.1:27029/ridu?directConnection=true&replicaSet=ridu-rs0. --no-docker therefore requires DATABASE_URL/--database-url for MongoDB. A standalone mongod is not supported because Ridu operations require transactions.

For SQLite development, use --database-path ./data/content.sqlite, RIDU_SQLITE_PATH, or the project-local .ridu/development.sqlite default. The generated production binary requires an absolute RIDU_SQLITE_PATH or absolute file: URI.

See each adapter guide for setup and production limits:

• Add PostgreSQL to an existing project
• Add SQLite to an existing project
• Add MongoDB to an existing project

Ridu does not provide a generic live cross-adapter migration facility. Moving existing data between adapters is an application-owned export, transform, validation, recovery, and cutover.

ridu dev --no-install skips dependency installation, and --no-sync disables additive development sync. Use these options only when another tool performs the omitted step.

Recover an interrupted installation

If dependency setup fails, fix the reported cause, install the missing dependencies, and restart development:

cd content
go mod tidy
npm install
ridu doctor
npm run dev

The example uses npm; replace its commands with the manager recorded in ridu.toml. ridu doctor checks tool availability, structural ridu.toml settings, the presence of frontend dependencies, and basic adapter prerequisites. It does not compile Go config, compare all release versions, check generated-contract drift, or connect to the database. Use ridu generate --check to resolve config and check committed contracts, then ridu check for Go and frontend validation. Continue with Troubleshooting when a scaffold still does not start.

Next read Project structure, Fields, and Generated contracts.