Package naming

Ionize has two distributable npm packages:

@nannier/canvas, the design system.
@nannier/sdk, the shared settings/encryption library.

(Plus @nannier/ionctl as the CLI, distributed via npm but not consumed as a library.)

The `@nannier/` scope

All Ionize packages are scoped under the @nannier npm scope.

Reasons:

Avoids name collisions in the global npm namespace.
Visible grouping, everything @nannier/* is from us.
Per-scope access policy: can require auth for publish.

Source-only contract

Both packages ship raw TypeScript via package.json:

{
  "name": "@nannier/sdk",
  "main": "./src/index.ts",
  "types": "./src/index.ts"
}

No build step at publish time. Consumers' build pipelines (Bun, Next.js, Vite) handle transpilation.

See ADR 0012, Source-only NPM packages for the rationale.

Consumer setup

Consumers list as a peer dependency:

"peerDependencies": {
  "@nannier/sdk": "^1.0.0"
}

And install:

bun add @nannier/sdk

The consumer's tsconfig.json and bundler config must:

Resolve .ts extensions (Bun and Next.js do this by default).
Apply Tailwind to node_modules/@nannier/canvas (for Canvas's classes to be in the final CSS):

// tailwind.config.js or v4 CSS-first
content: [
  "./src/**/*.{ts,tsx}",
  "./node_modules/@nannier/canvas/**/*.{ts,tsx}",  // critical
]

Version pinning

Ionize consumers (Dashboard, Auth, Site) typically use caret ranges (^1.0.0) for the SDK and Canvas. Updates within the major version are auto-pulled.

For maximum reproducibility, exact-pin:

"dependencies": {
  "@nannier/canvas": "2.10.0",
  "@nannier/sdk": "1.4.2"
}

bun.lock then encodes the exact resolved version.

When to update

Each app repo has a dependabot.yml that PRs version bumps. Review the changeset and merge if compatible.

For major version bumps, read the CHANGELOG carefully and adjust consumer code accordingly.

Linking for live dev

To edit Canvas / SDK and see changes in Dashboard immediately:

cd Ionize/canvas
bun link

cd ../dashboard
bun link @nannier/canvas

Unlink to go back to the published version:

cd Ionize/dashboard
bun unlink @nannier/canvas
bun install