@commonpub/config

Configuration factory and validation for CommonPub instances.

Overview

Every CommonPub instance has a commonpub.config.ts file that defines its identity, feature flags, and auth settings. defineCommonPubConfig() validates configuration at startup, applies defaults, and surfaces warnings about risky combinations.

Installation

pnpm add @commonpub/config

Usage

// commonpub.config.ts
import { defineCommonPubConfig } from '@commonpub/config';

const { config, warnings } = defineCommonPubConfig({
  instance: {
    domain: 'hack.build',
    name: 'hack.build',
    description: 'A maker community for hardware hackers',
    contactEmail: '[email protected]',
    maxUploadSize: 10 * 1024 * 1024, // 10MB
    contentTypes: ['project', 'blog', 'explainer'],
  },
  features: {
    content: true,
    social: true,
    hubs: true,
    docs: true,
    video: true,
    contests: false,
    learning: true,
    explainers: true,
    federation: false,
    admin: false,
  },
  auth: {
    emailPassword: true,
    magicLink: false,
    passkeys: false,
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
  },
});

Feature Flags

All features are gated behind flags (CLAUDE.md rule #2). No feature code runs unless its flag is true. New flags MUST also be declared in runtimeConfig.public.features in apps/reference/nuxt.config.ts — env-var overrides only propagate to declared keys (feedback-nuxt-env-only-declared-keys).

| Flag | Default | Controls | | --------------------- | ------- | ------------------------------------------------------------------------- | | content | true | Content CRUD, publishing, slugs | | social | true | Likes, comments, follows, bookmarks | | hubs | true | Hub system (community / product / company types) | | docs | true | Documentation module (CodeMirror, versioning, search) | | video | true | Video content type | | contests | false | Contest / competition system + judging workflow | | events | false | Events (listing, RSVP, calendar) | | learning | true | Learning paths, enrollment, progress, certificates | | explainers | true | Interactive explainer modules | | federation | false | ActivityPub federation (push + pull). Requires CPUB_FED_TOKEN_KEY env | | seamlessFederation | false | Display mirrored content alongside local content in browse / search / feed | | federateHubs | false | Hub federation via AP Group actors | | editorial | false | Editorial curation (staff picks, content categories, homepage editorial) | | admin | false | Admin panel (user mgmt, reports, settings, theme editor, layouts) | | emailNotifications | false | Email delivery for notifications (instant + digest) | | publicApi | false | Admin-provisioned public Read API at /api/public/v1/* (no keys created by flag flip; provision via /admin/api-keys) | | contentImport | true | URL content import — operator off-switch for the remote-fetch surface | | layoutEngine | false | Layout engine — <LayoutSlot> reads from layouts/layout_rows/layout_sections (migration 0005). Flip OFF if migration not applied — empty pages otherwise. Editor lives at /admin/layouts |

identity sub-flags

Identity features ship behind a nested object so the rollout can ratchet phase-by-phase. CPUB_FED_TOKEN_KEY env var MUST be set before flipping any phase to true (otherwise the runtime guards on each surface refuse to deploy).

| Sub-flag | Phase | Controls | | ------------------ | ----- | --------------------------------------------------------------------- | | linkRemoteAccounts | 1 | Users can link a remote Mastodon-API account (read-only) | | signInWithRemote | 2 | New users can sign up by signing in via a remote instance | | actingAs | 3 | "Acting as" identity-context switcher + banner | | remoteInteract | 4a | Like / comment / follow via a linked identity (low blast radius) | | remotePublish | 4b | Publish via a linked identity (highest blast radius — last to flip) |

Auth Configuration

| Option | Type | Description | | ----------------- | --------- | ---------------------------------------------- | | emailPassword | boolean | Email/password sign-up and sign-in | | magicLink | boolean | Passwordless magic link auth | | passkeys | boolean | WebAuthn/passkey support | | github | object? | GitHub OAuth { clientId, clientSecret } | | google | object? | Google OAuth { clientId, clientSecret } | | sharedAuthDb | string? | Shared auth DB connection string (Model C) | | trustedInstances| string[]?| Trusted instance domains for AP Actor SSO |

Warnings

defineCommonPubConfig() returns warnings for risky configurations:

• Shared auth DB: warns about database-level coupling between instances
• Federation without trusted instances: AP Actor SSO requires at least one
• Learning without explainers: explainers are a first-class lesson type

Exports

// Factory
export { defineCommonPubConfig } from './config';

// Types
export type { CommonPubConfig, FeatureFlags, AuthConfig, InstanceConfig } from './types';

// Zod schemas (for custom validation)
export { configSchema, featureFlagsSchema, authConfigSchema, instanceConfigSchema } from './schema';

Development

pnpm build        # Compile TypeScript
pnpm test         # Run 23 tests
pnpm typecheck    # Type-check without emitting

Dependencies

• zod: Schema validation