@novahelm/config

Configuration package for NovaHelm -- defines the NovaConfig type, the defineConfig() factory, environment variable schema, and billing plan utilities.

Quick Start

pnpm add @novahelm/config

Create a novahelm.config.ts at your project root:

import { defineConfig } from "@novahelm/config";

export default defineConfig({
  app: {
    name: "My App",
    url: "https://myapp.com",
    supportEmail: "[email protected]",
  },
  features: {
    blog: true,
    analytics: true,
  },
  auth: {
    providers: ["credential", "google", "github"],
    requireEmailVerification: true,
    enableMfa: true,
  },
});

All properties are optional -- defineConfig() deep-merges your overrides with sensible defaults.

NovaConfig Sections

| Section | Key Options | |---------|-------------| | app | name, url, supportEmail, defaultCurrency, defaultLocale | | features | multiTenant, realtime, blog, analytics, remoteConfig, monitoring, sync | | defaultModules | Module slugs to auto-enable on new projects (e.g. ["commerce", "ai"]) | | auth | providers, requireEmailVerification, enableMfa, enableImpersonation, sessionMaxAge | | admin | basePath, requireRole, enableAuditLog, enableFeedbackWidget | | plans | Array of PlanConfig (billing tiers with Stripe IDs, limits, features) | | onboarding | enabled, steps[] with id, title, description | | notifications | inApp, email, push, sms, discord | | content | enableComments, enableNewsletter, legalPages | | analytics | provider, retentionDays, trackPageViews, trackCommerce | | health | probeIntervalMs, alertAfterFailures, notifyChannels | | engagement | enableSubscriptions, enablePersonas, digestSchedule | | storage | maxUploadSizeMb, allowedMimeTypes, enableVideoProcessing | | ai | provider, embeddingModel, embeddingDimensions, defaultModel | | rateLimit | enabled, tiers (public/authenticated/apiKey/sensitive), recordViolations | | backup | encryptionKey, defaultRetention, notifyOnFailure | | agent | enabled, maxConcurrent, executionTimeoutMs |

Billing Plans

Define billing tiers with Stripe integration, usage limits, and feature gates:

import { defineConfig } from "@novahelm/config";
import type { PlanConfig } from "@novahelm/config";

export default defineConfig({
  plans: [
    {
      id: "free",
      name: "Free",
      stripeProductId: "prod_free",
      stripePriceIds: { monthly: "price_free_mo" },
      roleSlug: "user",
      limits: { teamMembers: 1, storageBytes: 500_000_000 },
      features: ["basic-analytics"],
      sortOrder: 0,
    },
    {
      id: "pro",
      name: "Pro",
      stripeProductId: "prod_pro",
      stripePriceIds: { monthly: "price_pro_mo", yearly: "price_pro_yr" },
      roleSlug: "user",
      limits: { teamMembers: 10, storageBytes: 50_000_000_000 },
      features: ["basic-analytics", "ai", "priority-support"],
      sortOrder: 1,
      recommended: true,
    },
  ],
});

Plan Utilities

import { getPlan, getRecommendedPlan, getSortedPlans } from "@novahelm/config";

const plans = config.plans;
const pro = getPlan(plans, "pro");           // Find by ID
const recommended = getRecommendedPlan(plans); // Get recommended (or first)
const sorted = getSortedPlans(plans);         // Sort by sortOrder

Environment Variables

The config package includes a type-safe environment variable schema with Zod validation, scoped by runtime and deployment tier:

import { createNovaEnv } from "@novahelm/config";

const env = createNovaEnv({
  runtime: "nextjs",  // "nextjs" | "node" | "edge"
});

// All env vars are validated and typed
env.DATABASE_URL;     // string (required)
env.RESEND_API_KEY;   // string | undefined (optional)

Environment Schema

import {
  FORGE_ENV_VARS,
  getEnvVarsByScope,
  getEnvVarsByGroup,
  getRequiredVarsForTier,
  getEnvGroups,
} from "@novahelm/config";

// Get vars needed for production
const prodVars = getRequiredVarsForTier("production");

// Get vars by functional group
const dbVars = getEnvVarsByGroup("database");
const authVars = getEnvVarsByGroup("auth");

Platform Environment Client

Fetch environment variables from the NovaHelm Console platform API:

import { fetchEnvFromPlatform, clearPlatformEnvCache } from "@novahelm/config";

const env = await fetchEnvFromPlatform({
  platformUrl: "https://console.novahelm.dev",
  projectSlug: "my-app",
  apiKey: process.env.NOVA_API_KEY!,
});

API Reference

| Export | Description | |--------|-------------| | defineConfig(overrides) | Create a NovaConfig with defaults deep-merged | | NovaConfig | Full configuration type | | PlanConfig | Billing plan definition type | | getPlan(plans, id) | Find a plan by ID | | getRecommendedPlan(plans) | Get the recommended plan | | getSortedPlans(plans) | Sort plans by sortOrder | | createNovaEnv(options) | Create a validated environment object | | FORGE_ENV_VARS | Full environment variable schema | | getEnvVarsByScope(scope) | Filter vars by scope (server/client) | | getEnvVarsByGroup(group) | Filter vars by functional group | | getRequiredVarsForTier(tier) | Get required vars for deployment tier | | getEnvGroups() | List all env var groups | | fetchEnvFromPlatform(opts) | Fetch env vars from Console API | | clearPlatformEnvCache() | Clear cached platform env vars |