@galaxy-io/create-galaxy-app

Scaffolds a Galaxy React app on @galaxy-io/dls: Vite with the DLS Linaria preset, Biome with the DLS rules, the three stylesheets, GalaxyProvider, and a template's screens.

pnpm create @galaxy-io/galaxy-app my-app
# or: npx @galaxy-io/create-galaxy-app my-app

Templates

| Name | What you get | |---|---| | app (default) | The Filament app skeleton, thin: TanStack Router file routes (src/routes), TanStack Query over ConnectRPC (connect-query) with one sample proto in protos/ generated into src/gen (pnpm codegen), an in-memory mock of that service in src/mock behind a router transport (set VITE_API_URL to talk to a server instead), one query hook in src/api/queries, the frame in src/layouts/main (MainLayoutSidebar or MainLayoutNavbar around the island, PageLayout (src/layouts/page) for a page's Topbar and toolbar), and two pages: a home placeholder and a sources table with search in the URL. The sample service is example.v1.ExampleService, named so it never collides with a module the app mounts, and its mock registers on a router (registerMockServices) so a module's mocks can join it behind one transport. Folders, names and imports follow Filament's ui/src (layouts/, pages/<feature>/components/, per-folder constants.ts / utils.ts, default exports, the @/ alias). | | blank | main.tsx with the stylesheets and the provider, and one page. |

Every template ships index.html (data-gx-theme="dark" for the first paint), vite.config.ts with galaxyDls({ prefix }), biome.json extending @galaxy-io/dls/biome, a strict tsconfig.json (exactOptionalPropertyTypes, noUncheckedIndexedAccess), a .gitignore, and dev / build / preview / typecheck / lint / lint:fix scripts.

Options

In a terminal the CLI asks for whatever you leave out, with arrow-key prompts; --yes (or a non-interactive shell) takes the defaults. Color follows the terminal and NO_COLOR.

create-galaxy-app [directory] [options]

  --template <name>        app | blank (default: app)
  --frame <name>           sidebar | navbar (default: sidebar; the app template)
  --theme <name>           system | dark | light (default: system)
  --brand <name>           galaxy | filament (default: galaxy; the app template)
  --name <package-name>    The package name (default: the directory name)
  --pm <manager>           pnpm | npm | yarn | bun (default: the one running this command, else pnpm)
  --dls <spec>             The @galaxy-io/dls version or range (default: the published version)
  --yes                    Take the defaults for everything not given; ask nothing
  --no-install             Write the files only
  --no-git                 Do not run git init
  --force                  Write into a directory that already has files
  --list                   Print the templates and the choices, then exit

| Choice | What it changes in the app | |---|---| | Frame | src/layouts/main/MainLayout.tsx renders MainLayoutSidebar (sidebar) or MainLayoutNavbar (Filament's top bar). Both files ship, so the other is a one-line swap later. | | Theme | GalaxyProvider theme in main.tsx and data-gx-theme on <html> for the first paint (system paints dark until the OS theme is read). | | Brand | src/components/Wordmark.tsx imports GalaxyWordmark or GalaxyFilamentWordmark; both frames render it. |

The CLI reads the published @galaxy-io/dls version from npm and writes ^<version>; offline it writes latest. --dls link:../dls or --dls file:../galaxy-io-dls-2.6.0.tgz points a mock at a local checkout or a packed build.

Before it is on npm

Until the package is published, run it from a checkout of the DLS repository:

cd dls && pnpm install && pnpm create-app ../my-app

pnpm create-app runs the CLI from source; the scaffolded app installs @galaxy-io/dls from npm like any other. To point a mock at unreleased DLS changes instead, pack the local build and pass the tarball: pnpm build && pnpm pack, then pnpm create-app ../my-app --dls file:$PWD/galaxy-io-dls-<version>.tgz.

In the DLS repository

| Script | What it does | |---|---| | pnpm create-app <dir> | Runs the CLI from source (src/cli.ts, Node type stripping). | | pnpm templates:check | In pnpm verify: the registry and the folders agree, every template has its scaffolding files, only known {{placeholders}} appear, every optional peer a template needs is declared, and each template, scaffolded in two variants into .cache/templates-check/ (git-ignored), type-checks against src/ and passes Biome with the repository's config. | | pnpm templates:smoke | After pnpm build: packs the package, scaffolds each template onto the tarball in a temp directory, installs, type-checks, lints and builds with Vite. Needs the network. | | pnpm create-app:build | Builds dist/ (the published bin) and checks the package with publint. |

Releasing

Run the Release create-galaxy-app workflow on GitHub (or gh workflow run "Release create-galaxy-app" -f bump=patch). It checks everything above, bumps this package's version, commits and tags create-galaxy-app-v<version>, and publishes through the trusted publisher configured on npmjs.com for release-create-galaxy-app.yml. It is independent of the DLS release; never bump the version by hand.

Adding a template

1. Add a folder under templates/. Files named _gitignore and _biome.json are renamed to .gitignore and biome.json on copy (npm drops .gitignore from packages; a nested biome.json would apply to this repository). Use the placeholders in src/templates.ts ({{name}}, {{title}}, {{prefix}}, {{dlsVersion}}, {{frame}}, {{frameModule}}, {{theme}}, {{themeAttribute}}, {{wordmark}}, {{wordmarkModule}}) where the app's values go. The raw templates are not linted in place (placeholders sit in code positions); pnpm templates:check scaffolds each in two variants and runs tsc and Biome on the output, so keep them formatted.
2. Register it in src/templates.ts (TEMPLATES, TemplateName).
3. pnpm templates:check, then pnpm templates:smoke once.
4. Describe it in docs/getting-started.md and add a changeset.

The package has no runtime dependencies; the app template's router, query and ConnectRPC packages are dev dependencies so it type-checks here.