create-giojs

Scaffold a new GioJS app, add starter features to an existing one, or migrate a Next.js project - every flag, prompt and exit code.

npm create giojs@latest my-app

pnpm create giojs my-app

yarn create giojs my-app

bun create giojs my-app

npm create giojs@latest [directory] -- [options]
npm create giojs@latest -- add <feature...> [options]
npm create giojs@latest -- migrate [dir] [options]

With npm, options after the directory go behind --. pnpm, yarn and bun pass that -- on, and create-giojs skips it, so the documented form works under every package manager.

Reference

--pm and --features take their value as the next argument or after = (--pm=pnpm). Boolean flags take no value.

Prompts

On a terminal, create-giojs asks for what the flags leave open, in this order, before it writes anything:

1. Project name (when no directory is given; default my-giojs-app). A directory that is not empty is refused here and asked again.
2. Package name, only when the directory's name is not a valid npm name (My App suggests my-app).
3. Language: TypeScript or JavaScript.
4. What are you building? Server app or static site.
5. Add features: a multi-select of the starter features that fit the build target.
6. Install dependencies with <pm>?

Without a terminal (CI, piped input) or with --yes, nothing is asked: the directory defaults to my-giojs-app, an invalid package name is replaced by its sanitized form with a warning, and no features are added. Ctrl+C at a question exits with code 130 and nothing written; Ctrl+C while files are being written removes what this run created (except in a --force run, whose overwritten files cannot be restored).

What it writes

• The starter: app/ with a root layout, an app/(site)/ route group (home, about, a dynamic post page), error and not-found pages, components/, public/ with self-hosted fonts, gio.toml, tsconfig.json (or jsconfig.json), .env.example, .gitignore and AGENTS.md.
• package.json with @gio.js/server, @gio.js/core, @gio.js/react, React and cross-env. Its scripts run cross-env NODE_ENV=development giojs-server (dev) and cross-env NODE_ENV=production giojs-server (start).
• The chosen features' files, then the install, then the git commit (so it includes the lockfile).

Over an existing directory, the initial commit holds only what this run wrote: files that were already there are left out and listed, as they may hold secrets.

The target directory

A directory that is not empty is refused, with a list of what is in it, unless --force. These do not count: .git, .gitattributes, .DS_Store, Thumbs.db, .idea, .vscode, README.md and LICENSE (.md, .txt). A path that exists and is not a directory is always refused.

Starter features

Asking a static site for a server feature is a usage error before anything is written. Each feature's next steps are printed at the end, with the commands of the package manager the app was installed with. See Starter Features.

create-giojs add

npx create-giojs add <feature...> [--cwd <dir>] [--dry-run] [-f, --force]

Adds starter features to an existing project, without overwriting files you changed; gio add runs it. Features are named as arguments (tailwind auth, tailwind,auth) or with the create flags (--auth, --features auth,db). The gio add page has the behavior, conflicts and exit codes.

create-giojs migrate

npm create giojs@latest -- migrate [dir] [--dry-run | -n] [-y, --yes] [--config <file>]
npx create-giojs migrate [dir]
npx -p create-giojs gio-migrate [dir]    # the standalone bin

Migrates a Next.js project to GioJS in place; gio migrate runs it and documents every option. A bare npx gio-migrate would fetch whatever npm package has that name: use npx -p create-giojs gio-migrate.

Exit codes

Examples

Create an app in CI

npm create giojs@latest my-app -- --yes --no-git

A JavaScript static site

npm create giojs@latest my-site -- --js --static

pnpm create giojs my-site --js --static

yarn create giojs my-site --js --static

bun create giojs my-site --js --static

A server app with features

$ npm create giojs@latest shop -- --tailwind --auth --no-install
Creating shop in /home/me/shop - TypeScript (.tsx), server app...
Template copied.
Added: Tailwind CSS, Authentication.
Initialized a git repository with an initial commit.

Done! To get started:

  cd shop
  npm install
  npm run dev

Your features:
  Tailwind CSS:
    - Use Tailwind classes in any component - `npm run dev` runs the Tailwind watcher next to the server.
    - The starter's own styles now load from app/tailwind.css (in Tailwind's base layer).
  Authentication:
    - Open /dashboard: the guard sends you to /login (demo user in .env.development).
    - Before deploying, generate GIO_SESSION_SECRET: node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
    - Cross-site POSTs are refused by the server (CSRF), so forms need no tokens; keep state changes behind POST.

With pnpm, in the current directory

mkdir blog && cd blog
pnpm create giojs .

Mistakes it catches

$ npm create giojs@latest x -- --statc
Error: Unknown option --statc - did you mean --static?
Run create-giojs --help to see every option.

$ npm create giojs@latest site -- --static --auth
Error: auth needs a server app - a static site has no server to run it.

Good to know

• The package manager is the one you ran (npm create, pnpm create, yarn create, bun create), unless --pm says otherwise - so a pnpm user never ends up with two lockfiles.
• The package name must be a valid npm name: lowercase, URL-safe, at most 214 characters, not a Node.js built-in module. The validated name is what goes into the templates.
• Git is skipped with a note when git is not installed or the directory is already inside a repository; a failed commit (no user.name) leaves an initialized repository for you to commit.
• A mistyped option never silently scaffolds something else: unknown flags are errors. A misspelled subcommand is a plain word, though, so npm create giojs@latest -- migrat scaffolds a new app in migrat/ - check the Creating ... in ... line.

Related

• Installation
• Starter Features and gio add
• Migration from Next.js and gio migrate
• Static Export
• CLI overview

Version history