gio add

Add starter features - Tailwind, an API route, authentication, a database, Docker, CI - to an existing GioJS app, without overwriting files you changed.

npx gio add tailwind auth

pnpm exec gio add tailwind auth

yarn gio add tailwind auth

bunx gio add tailwind auth

gio add <feature...> [--cwd <dir>] [--dry-run] [--force]

Reference

Features

Features are always applied in that order, whatever order you name them in. The Starter Features page lists every file each one writes.

Behavior

gio add runs create-giojs add with your arguments, finding create-giojs the way gio migrate does (installed copy first, else the same version through npx / pnpm dlx / bunx, never a release without the subcommand). Then:

1. It reads the project: package.json must exist, with a gio.toml or an app/ directory. TypeScript or JavaScript comes from tsconfig.json / jsconfig.json; a build script running gio export marks a static site; the package manager comes from the lockfile.
2. It plans the whole run. A feature that is already set up (all its files exist) keeps your edits and changes nothing. For a new feature, a file of yours in its way is a conflict, and the run stops before anything is written, with a diff.
3. It writes the files, merges package.json dependencies and scripts, adds gio.toml tables and keys (a project without gio.toml gets one), .env lines, .gitignore lines and a note in AGENTS.md, then prints the next steps.

Examples

Preview a feature

$ npx gio add docker --dry-run
Would create:
  docker-compose.yml
  .dockerignore
  Dockerfile
Would update:
  AGENTS.md

Next steps:
  Docker:
    - docker compose up --build   (or: docker build -t my-app .)
    - Server secrets go in .env.production.local (git- and docker-ignored), which docker-compose.yml passes to the container.

Add a feature

$ npx gio add api
Did create:
  components/forms.css
  app/(site)/guestbook/page.tsx
  app/api/guestbook/route.ts
  lib/guestbook.server.ts
Did update:
  AGENTS.md

Next steps:
  API route + form:
    - Open /guestbook for the form; the same entries are JSON at /api/guestbook.

When a feature adds dependencies, the output ends with the install command to run (Run `npm install` to install ...); gio add does not install them itself.

A conflict

$ npx gio add docker
Nothing was written - these files differ from what the feature adds:
  Dockerfile: exists with different content
      - FROM node:22
      + # syntax=docker/dockerfile:1
      + # Production image for my-app: `gio build standalone` packs the app
      ...

Keep your version (rename or merge it by hand), or rerun with --force to overwrite.

Run it again

$ npx gio add auth
Authentication is already set up - nothing to change.

Good to know

• Exit codes: 0 when the features were added (or previewed, or were already there); 1 when the run was refused - a conflict, a server feature for a static site, no project in the directory; 2 for an unknown option or feature, or no feature at all.
• A server feature on a static site is refused: Cannot add auth to a static site: it needs the GioJS server (build: gio export has none).
• --force overwrites conflicting files, but not a page of yours that serves the same URL from another folder: that conflict needs a manual fix.
• Feature pages go into the app/(site)/ route group and import lib/ by relative path, so a @/* alias of yours does not break them.

Related

• Starter Features
• create-giojs add and the create-time flags
• Guides: Tailwind, Authentication Example, Database, Docker

Version history