@geenius/config

The single source of truth for Geenius runtime app configuration (geenius.config.ts) plus shared TypeScript and Biome presets. Design tokens now live in the separate @geenius/tokens package.

Installation

pnpm add @geenius/config

If you only consume the TypeScript or Biome presets at build time, installing as a dev dependency is also valid:

pnpm add -D @geenius/config

Biome consumers also need the Biome CLI in the consumer workspace:

pnpm add -D @geenius/config @biomejs/biome

What's Inside

| Sub-Package | Purpose | |-------------|---------| | @geenius/config/typescript/* | Strict TypeScript configs (base, react, solidjs, library, node) | | @geenius/config/biome | Shared Biome config for linting + formatting | | @geenius/config (root) | Runtime app config — defineConfig(), getConfig(), Zod validation |

Published Subpaths

@geenius/config is a special family package, so its root export map intentionally ships a mix of runtime helpers and JSON presets instead of React or SolidJS UI variants.

| Import | Purpose | |--------|---------| | @geenius/config | Runtime config authoring, loading, validation, and diagnostics | | @geenius/config/app | Compatibility alias for the root runtime config entrypoint | | @geenius/config/biome | Shared Biome configuration JSON | | @geenius/config/typescript | Compatibility alias for the shared TypeScript base preset | | @geenius/config/typescript/base | Shared TypeScript baseline | | @geenius/config/typescript/react | React TypeScript preset | | @geenius/config/typescript/solidjs | SolidJS TypeScript preset | | @geenius/config/typescript/library | Library build TypeScript preset | | @geenius/config/typescript/node | Node-focused TypeScript preset |

Subpath Examples

Biome JSON preset

{
  "$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
  "extends": ["@geenius/config/biome"]
}

TypeScript preset subpaths

{
  "extends": "@geenius/config/typescript/base"
}

{
  "extends": "@geenius/config/typescript/react"
}

{
  "extends": "@geenius/config/typescript/solidjs"
}

{
  "extends": "@geenius/config/typescript/library"
}

{
  "extends": "@geenius/config/typescript/node"
}

Quick Start

TypeScript

{
  "extends": "@geenius/config/typescript/react"
}

Available configs: base, react, solidjs, library, node.

Biome

Install both the config preset and the Biome CLI:

pnpm add -D @geenius/config @biomejs/biome

{
  "$schema": "https://biomejs.dev/schemas/2.4.14/schema.json",
  "extends": ["@geenius/config/biome"]
}

Design Tokens

Use @geenius/tokens directly for CSS variables and theme data. It owns the --gn-* namespace, including dark-mode selectors in the same stylesheet.

@import "@geenius/tokens";

App Config (geenius.config.ts)

Create a geenius.config.ts in your project root:

import { defineConfig } from '@geenius/config';

export default defineConfig({
  name: 'My App',
  version: '1.0.0',
  tier: 'lancio',

  auth: {
    providers: ['email', 'google'],
    sessionExpiry: 7200,
  },

  features: { payment: true },

  payment: {
    provider: 'stripe',
    currency: 'USD',
    products: [
      { id: 'starter', name: 'Starter', price: 29, recurring: 'month' },
      { id: 'pro', name: 'Pro', price: 99, recurring: 'month' },
    ],
  },

  email: {
    provider: 'resend',
    fromAddress: '[email protected]',
    fromName: 'My App',
  },

  database: { provider: 'neon' },

  i18n: {
    defaultLocale: 'en',
    supportedLocales: ['en', 'es'],
    routePrefix: true,
  },

  deployment: { platform: 'cloudflare' },
});

Load and use at runtime:

import { initConfig, getConfig, isFeatureEnabled } from '@geenius/config';

// At app startup
await initConfig();

// Anywhere in your app
const config = getConfig();
config.auth.providers;     // ['email', 'google']
config.payment?.provider;  // 'stripe'
isFeatureEnabled('payment'); // true

Tiers

The config validates differently based on your tier:

| | Pronto | Lancio | Studio | |-|--------|--------|--------| | Purpose | Rapid prototyping | Production-ready | Full-featured + branding | | Auth | Required; email is typical | Required (at least email) | Required + MFA support | | Payment | Not allowed | Required if features.payment | Required if features.payment | | Email | Mock allowed | Real provider required | Real provider required | | Database | Memory allowed | Real provider required | Real provider required | | Brand | Not allowed | Not available | Optional | | Features | Limited | Standard | All |

Pronto (prototyping)

defineConfig({
  name: 'Pronto Prototype',
  version: '0.1.0',
  tier: 'pronto',
  auth: { providers: ['email'] },
  email: { provider: 'mock', fromAddress: 'dev@localhost' },
  database: { provider: 'memory' },
  i18n: { defaultLocale: 'en', supportedLocales: ['en'], routePrefix: false },
  deployment: { platform: 'cloudflare' },
  // No payment, no brand — validation enforces this
});

Lancio (production)

defineConfig({
  name: 'Lancio App',
  version: '1.0.0',
  tier: 'lancio',
  auth: { providers: ['email', 'google'] },
  email: { provider: 'resend', fromAddress: '[email protected]' },
  database: { provider: 'neon' },
  i18n: { defaultLocale: 'en', supportedLocales: ['en'], routePrefix: true },
  deployment: { platform: 'cloudflare' },
  features: { payment: true },
  payment: {
    provider: 'stripe',
    currency: 'USD',
    products: [{ id: 'pro', name: 'Pro', price: 9900, recurring: 'month' }],
  },
  // Mock email/memory DB would fail validation
});

Studio (enterprise)

defineConfig({
  name: 'Studio App',
  version: '1.0.0',
  tier: 'studio',
  auth: { providers: ['email', 'google', 'github', 'passkey'], mfaRequired: true },
  email: { provider: 'resend', fromAddress: '[email protected]' },
  database: { provider: 'neon' },
  i18n: { defaultLocale: 'en', supportedLocales: ['en'], routePrefix: true },
  deployment: { platform: 'cloudflare' },
  brand: {
    name: 'My Brand',
    logo: '/logo.svg',
    colors: { primary: 'oklch(0.65 0.22 265)' },
  },
});

API Reference

Config Lifecycle

| Function | Description | |----------|-------------| | defineConfig(config) | Type-safe helper for geenius.config.ts files | | initConfig(path?) | Load, validate, and cache config from file | | getConfig() | Get the cached config singleton (throws if not initialized) | | setConfig(config) | Set config programmatically (validates before caching) | | resetConfig() | Clear the cache (for testing) | | validateConfig(config, tier?) | Validate a config object, returns validated config or throws |

Typed Accessors

| Function | Returns | |----------|---------| | getTier() | 'pronto' \| 'lancio' \| 'studio' | | getAuthProviders() | AuthProvider[] | | getPaymentProvider() | PaymentProvider \| null | | getEmailProvider() | EmailProvider | | getDatabaseProvider() | DatabaseProvider | | getAnalyticsProvider() | AnalyticsProvider \| null | | getDeploymentPlatform() | DeploymentPlatform | | getConfiguredProviders() | Provider and deployment-platform summary | | getSupportedLocales() | string[] | | getDefaultLocale() | string | | getFeatureFlags() | Readonly<Record<string, boolean>> | | getEnabledFeatureFlags() | string[] | | isFeatureEnabled(name) | boolean |

Doctor & Introspection

| Function | Description | |----------|-------------| | doctorValidateConfig(config, env?) | Full validation report: errors, warnings, suggestions, missing env vars | | introspectConfig(config) | Extract metadata: providers, features, locales, tier | | getRequiredEnvVars(config) | List of env vars required by configured providers | | checkMissingEnvVars(config, env?) | Which required env vars are missing |

Adapter Integration

| Function | Description | |----------|-------------| | toAdapterConfig(config, env?) | Convert GeeniusConfig to AdapterConfig for @geenius/adapters | | shouldUseMockAdapters(config) | Check if config should use localStorage mocks (Pronto) | | getConfiguredDomains(config) | List which adapter domains are configured |

Advanced Runtime Exports

The root runtime entrypoint also exposes the underlying Zod schemas and typed error contract for package authors and tooling:

import {
  ConfigError,
  authProviderSchema,
  baseConfigSchema,
  createConfigSchema,
  getProviderEnvVars,
  tierSchema,
} from "@geenius/config";

Use getProviderEnvVars() when you need provider-level env metadata, and use baseConfigSchema or createConfigSchema() when composing validation into setup tooling without re-implementing the config contract.

Environment Variables

Required env vars depend on your configured providers:

| Provider | Required Variables | |----------|-------------------| | stripe | STRIPE_API_KEY, STRIPE_WEBHOOK_SECRET | | lemon-squeezy | LEMON_SQUEEZY_API_KEY, LEMON_SQUEEZY_WEBHOOK_SECRET | | polar | POLAR_API_KEY | | resend | RESEND_API_KEY | | sendgrid | SENDGRID_API_KEY | | postmark | POSTMARK_API_KEY | | convex | CONVEX_DEPLOYMENT, CONVEX_URL | | neon | DATABASE_URL | | cloudflareKV | CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_KV_NAMESPACE_ID, CLOUDFLARE_API_TOKEN | | drizzle-neon | DATABASE_URL migration compatibility alias for neon; prefer neon in new configs | | posthog | POSTHOG_API_KEY, POSTHOG_HOST | | plausible | PLAUSIBLE_DOMAIN | | google (OAuth) | GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET | | github (OAuth) | GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET |

drizzle-supabase and drizzle-mongodb are post-launch compatibility strings only. They are accepted for forward migration metadata, but they are not V1 launch database providers, do not expose launch env vars, and should not be used for new launch configs.

Use getRequiredEnvVars(config) to programmatically determine what's needed, or call doctorValidateConfig(config, env) for a full runtime validation report.

Deployment Platforms

The runtime deployment platform vocabulary is cloudflare, vercel, netlify, and aws.

export default defineConfig({
  // ...
  deployment: { platform: 'aws' },
});

Design Tokens

@geenius/config no longer ships Tailwind presets, token CSS, or the UI bridge. Those assets moved to @geenius/tokens, which owns OKLCH-based CSS custom properties under the --gn-* namespace.

@import "@geenius/tokens";

:root {
  --gn-bg: oklch(0.985 0.005 264);
  --gn-text: oklch(0.13 0.02 264);
  --gn-accent: oklch(0.55 0.24 264);
}

Dark mode is provided by @geenius/tokens through [data-theme="dark"], .dark, or prefers-color-scheme: dark in the same stylesheet.

TypeScript Configs

All configs inherit from base.json with strict settings:

strict: true
noUnusedLocals: true
noUnusedParameters: true
noUncheckedIndexedAccess: true
exactOptionalPropertyTypes: true
noFallthroughCasesInSwitch: true
forceConsistentCasingInFileNames: true
isolatedModules: true

| Config | Adds | |--------|------| | react | jsx: react-jsx | | solidjs | jsxImportSource: solid-js, jsx: preserve, declaration: true, declarationMap: true, sourceMap: true, noEmit: false | | library | declaration: true, declarationMap: true, sourceMap: true, noEmit: false; set project-local rootDir/outDir in your own config | | node | module: Node16, moduleResolution: Node16, types: ["node"] |

Biome Config

Install the preset with the Biome CLI in the consuming workspace:

pnpm add -D @geenius/config @biomejs/biome

Shared config enforces:

• Recommended lint rules
• noExplicitAny: error
• 2-space indent
• Automatic import organization
• Ignores dist/, node_modules/, _generated/

Storybook

Storybook is intentionally not applicable for @geenius/config. This package is a non-UI special family that publishes runtime helpers and JSON presets rather than React or SolidJS components.

Testing

@geenius/config uses variants.json as the fixed-domain manifest for the gauntlet. It enumerates app, biome, and typescript; UI variants, Storybook, Playwright e2e, a11y, and visual regression are explicit N/A layers for this package.

| Layer | Script | |-------|--------| | Lint + publint | pnpm run lint, pnpm run lint:pub | | Type-check | pnpm run type-check | | Unit/property tests | pnpm run test:unit | | Workspace conventions | pnpm run test:conventions | | Export/parity contracts | pnpm run test:exports | | Dist/tarball contract | pnpm run test:dist-contract, pnpm run test:pack-contract | | Packed consumer smoke | pnpm run test:packed-smoke | | Packed type checks | pnpm run test:types | | Coverage + diff gate | pnpm run test:coverage, pnpm run test:diff-coverage | | Size budgets | pnpm run size | | Supply-chain/license/SBOM | pnpm run audit:supply-chain, pnpm run test:license, pnpm run sbom | | Runtime perf smoke | pnpm run test:perf | | Explicit UI N/A guards | pnpm run test:storybook, pnpm run test:a11y, pnpm run test:visual | | PR gauntlet | pnpm run test:gauntlet | | Full nightly/pre-release | pnpm run test:all | | Weekly mutation cron | pnpm run test:mutation |

Contributing tests

Add or change a config domain in variants.json first, then wire the domain package and public export map to match. Root scripts delegate package traversal to geenius-release pnpm-filters, and the packed smoke harness reads the manifest directly for config-specific static asset checks.

For runtime provider vocabulary, keep the launch labels convex, neon, cloudflareKV, and memory canonical. Compatibility labels such as drizzle-neon may remain tested, but new tests should prefer the canonical labels.

Contributing

See CONTRIBUTING.md.

License

FSL-1.1-Apache-2.0. Commercial usage is governed by the repository LICENSE.