create-package CLI

@tinycld/create-package is the scaffolder for new sibling packages. One command produces a repo that already passes the app shell’s generator checks, CI, and typecheck. It can run interactively (prompts for everything) or fully non-interactively (every prompt has a matching flag).

Usage

npx @tinycld/create-package <slug>

The positional argument is the package slug — kebab-case, 3–40 characters. It becomes:

• The npm name: @tinycld/<slug>
• The URL segment: /a/[orgSlug]/<slug>/
• The Go module path: tinycld.org/packages/<slug>

Omit the positional to be prompted for it.

Flags

Every prompt has a matching flag. Pass --yes to take defaults for everything else.

--no-link always wins over --yes — pass both when you want to scaffold without touching the app shell.

Non-interactive example

npx @tinycld/create-package my-feature \
    --yes \
    --preset full \
    --icon check-square \
    --no-server \
    --no-link

This scaffolds with all defaults, no Go server, and no app-shell linking. Suitable for CI, scripted setups, and autonomous coding agents.

Workspace detection

When --target is not set, the scaffolder picks one of two layouts based on the current directory:

• Attach — if <cwd>/tinycld/package.json declares "name": "tinycld", the new package goes to <cwd>/<slug>/. The existing app shell handles linking.
• Bootstrap — otherwise, the scaffolder creates <cwd>/tinycld-<slug>/, places the package at <cwd>/tinycld-<slug>/<slug>/, and (with --link) clones the app shell to <cwd>/tinycld-<slug>/tinycld/.

This means npx @tinycld/create-package my-todo from an empty directory produces a self-contained ./tinycld-my-todo/ workspace with everything you need to run the app, while running it from inside an existing ~/code/tinycld/ workspace just adds another sibling package next to your existing tinycld checkout.

The detection check is strict: it reads tinycld/package.json and matches name === "tinycld". A coincidentally-named directory won’t false-match.

Prompts (interactive mode)

Presets

full — data package

The shape of @tinycld/contacts, @tinycld/mail, @tinycld/calendar, @tinycld/drive. You get routes, a sidebar, an optional provider, pbtsdb collections, PocketBase migrations, seed data, and (optionally) a Go server stub.

settings-only — service package

The shape of @tinycld/google-takeout-import. The package contributes a single Personal Settings panel — no routes, no nav entry, no collections, no server. Use this for integrations and admin-style tools.

Generated files

Both presets produce:

• manifest.ts, package.json, tsconfig.json — lint config is not duplicated; tinycld/biome.json covers every linked package
• README.md, .gitignore
• .github/workflows/ci.yml — clones the app shell, links the package, runs lint (from the app shell) + typecheck + unit + e2e
• tests/manifest.test.ts — smoke test asserting the manifest shape

The full preset additionally produces:

• pb-migrations/<timestamp>_create_<slug>.js
• server/go.mod, server/register.go (if the Go server prompt is yes)
• tinycld/<slug>/{collections,provider,seed,sidebar,types}.ts
• tinycld/<slug>/screens/{_layout,[id],index}.tsx

The settings-only preset additionally produces:

• tinycld/<slug>/types.ts
• tinycld/<slug>/settings/main.tsx

After scaffolding

The CLI prints the steps it didn’t run — it never touches git or gh. Typical next steps:

cd my-feature
git init
git add .
git commit -m 'chore: initial scaffold'
gh repo create tinycld/my-feature --public --source=. --push

If you didn’t pass --link (or said no to the prompt), also link the package now:

cd ../tinycld
npm run packages:link ../my-feature
npm run checks

Linking the new package into the app shell is enough to see it in navigation; the generator wires routes, collections, migrations, and settings panels automatically.

Import conventions in scaffolded code

Templates use the scoped @tinycld/core path:

import { useOrgLiveQuery } from '@tinycld/core/lib/use-org-live-query'
import { Modal } from '@tinycld/core/ui/modal'

@tinycld/core isn’t a separate npm package or git repo — it’s bundled inside the app shell at tinycld/packages/@tinycld/core/. Resolution works because the sibling compiles in the app shell’s tsconfig context once linked.

Intra-package imports use relative paths; ~/tinycld/<slug>/* is also aliased to the package’s own nested source if you want an absolute form.

For the published source and template internals, see the create-package repo.