Skip to content

Modules

Jump to bottom
Ronak M. Parmar edited this page Mar 11, 2026 · 1 revision

Modules

A module is the fundamental building block of Foundation CLI. Every technology option — Next.js, PostgreSQL, JWT auth, Docker — is implemented as a module.

What Is a Module?

A module is a self-contained unit that declares everything needed to add a technology to a project:

interface ModuleManifest {
  id:           string;              // kebab-case, unique — e.g. "auth-jwt"
  name:         string;              // display name — e.g. "JWT"
  version:      string;              // semver
  category:     PluginCategory;      // see categories below
  description:  string;
  dependencies: PackageDependency[]; // npm / pip packages to install
  files:        FileEntry[];         // files to write (EJS templates)
  configPatches: ConfigPatch[];      // merges into package.json, tsconfig, .env, etc.
  compatibility: {
    conflicts: string[];             // module IDs that cannot coexist
  };
}

Modules may also export lifecycle hooks — functions that run at specific stages of the pipeline. See Architecture for details.

Module Categories

Frontend

Generates the client-side application scaffold, build configuration, and entry point files.

Module ID Key files generated
Next.js frontend-nextjs App Router layout, page, globals.css, next.config.mjs
React + Vite frontend-react-vite index.html, main.tsx, App.tsx, vite.config.ts
Vue 3 frontend-vue App.vue, main.ts, vite.config.ts
Svelte frontend-svelte App.svelte, main.ts, svelte.config.js, vite.config.ts

Adding a New Built-in Module

If you are contributing to Foundation CLI, follow these steps to add a new module:

  1. Create packages/modules/src/<category>/<name>.ts — use an existing module as a template
  2. Export a PluginDefinition with a unique id, category, and all required manifest fields
  3. Add the export to packages/modules/src/index.ts
  4. Add the import and entry to BUILTIN_MODULES in packages/modules/src/registry-loader.ts
  5. Add the selection → module ID mapping to SELECTION_TO_MODULE_ID
  6. Add a prompt choice to the appropriate array in packages/cli/src/prompt/graph-definition.ts
# Modules

A module is the fundamental building block of Foundation CLI. Every technology option — Next.js, PostgreSQL, JWT auth, Docker — is implemented as a module.

What Is a Module?

A module is a self-contained unit that declares everything needed to add a technology to a project:

interface ModuleManifest {
  id:           string;              // kebab-case, unique — e.g. "auth-jwt"
  name:         string;              // display name — e.g. "JWT"
  version:      string;              // semver
  category:     PluginCategory;      // see categories below
  description:  string;
  dependencies: PackageDependency[]; // npm / pip packages to install
  files:        FileEntry[];         // files to write (EJS templates)
  configPatches: ConfigPatch[];      // merges into package.json, tsconfig, .env, etc.
  compatibility: {
    conflicts: string[];             // module IDs that cannot coexist
  };
}

Modules may also export lifecycle hooks — functions that run at specific stages of the pipeline. See [Architecture](Architecture) for details.

Module Categories

Frontend

Generates the client-side application scaffold, build configuration, and entry point files.

Module ID Key files generated
Next.js frontend-nextjs App Router layout, page, globals.css, next.config.mjs
React + Vite frontend-react-vite index.html, main.tsx, App.tsx, vite.config.ts
Vue 3 frontend-vue App.vue, main.ts, vite.config.ts
Svelte frontend-svelte App.svelte, main.ts, svelte.config.js, vite.config.ts

Backend

Generates the server application, routing, middleware, and health endpoint.

Module ID Key files generated
Express backend-express server.ts with CORS, Helmet, health endpoint
NestJS backend-nestjs AppModule, AppController, AppService, main.ts
FastAPI backend-fastapi app/main.py, requirements.txt, CORS middleware
Django backend-django settings.py, urls.py, DRF views, requirements.txt

Database

Generates the database client, connection pooling, and initial migration.

Module ID Key files generated
PostgreSQL database-postgresql src/db/client.ts (node-postgres pool), 001_init.sql
MySQL database-mysql src/db/client.ts (mysql2 pool), 001_init.sql
MongoDB database-mongodb src/db/client.ts (native driver), 001_init.js
SQLite database-sqlite src/db/client.ts (better-sqlite3, WAL mode), 001_init.sql
Supabase database-supabase src/db/client.ts (anon + admin clients), init migration

Auth

Generates authentication middleware, route handlers, and token/session management.

Module ID Key files generated
JWT auth-jwt auth.service.ts, auth.middleware.ts, auth.router.ts
OAuth (Google + GitHub) auth-oauth oauth.config.ts, oauth.router.ts (Passport.js)
Session-based auth-session session.config.ts, session.middleware.ts, session.router.ts
Clerk auth-clerk clerk.middleware.ts, clerk.router.ts, AuthProvider.tsx
Auth0 auth-auth0 auth0.config.ts, auth0.middleware.ts, AuthProvider.tsx

UI

Generates the CSS/component framework configuration and provider wrappers.

Module ID Key files generated
Tailwind CSS ui-tailwind tailwind.config.js, postcss.config.js, globals.css
ShadCN/UI ui-shadcn tailwind.config.ts with CSS variables, components.json, utils.ts
Material UI ui-mui theme.ts, MuiProvider.tsx with AppRouterCacheProvider
Chakra UI ui-chakra ChakraProvider.tsx with extended theme
Bootstrap ui-bootstrap layout.tsx with Bootstrap import, custom.scss

State Management

Generates the client-side state store, provider wrapper, and usage examples.

Module ID Key files generated
Zustand state-zustand src/store/index.ts with devtools + persistence
Redux Toolkit state-redux store/index.ts, counterSlice.ts, ReduxProvider.tsx
TanStack Query state-tanstack-query query-client.ts, QueryProvider.tsx, example hooks

Deployment

Generates infrastructure configuration files for the target platform. See Deployment for details.

Module ID Key files generated
Docker deployment-docker Multi-stage Dockerfile, docker-compose.yml with Postgres
Vercel deployment-vercel vercel.json with CORS headers, .vercelignore
Render deployment-render render.yaml Blueprint with managed PostgreSQL
AWS deployment-aws ECS task definition, GitHub Actions CI/CD workflow

How Modules Compose Together

Dependency resolution

When you select multiple modules, the engine builds a dependency graph. Each module declares which other modules it conflicts with. The resolver checks every pair and aborts with a structured error if an unresolvable conflict is found (for example, selecting two auth modules simultaneously).

Configuration merging

Many modules need to patch shared files — package.json, tsconfig.json, .env.example, docker-compose.yml. Rather than overwriting these files, Foundation CLI merges patches using type-aware strategies:

File Merge strategy
package.json Deep merge — scripts, dependencies, devDependencies are merged key-by-key
tsconfig.json Deep merge — compilerOptions and paths are merged
.env.example Key deduplication — existing keys are preserved, new keys are appended
docker-compose.yml Service-level merge — each service block is merged independently
requirements.txt Package deduplication with semver intersection for version constraints

Topological execution order

Modules are written in topological dependency order. If module B depends on module A (for example, an auth module that requires a database module), module A is rendered and staged first.

Module Status

Modules carry a status field that the CLI enforces:

Status Behavior
stable Default. No restrictions.
experimental Warning printed. Blocked in CI unless --allow-experimental is passed.
deprecated Warning printed with successor information. Still usable.
removed Hard error. Migration guide URL is printed.

Adding a New Built-in Module

If you are contributing to Foundation CLI, follow these steps to add a new module:

  1. Create packages/modules/src/<category>/<name>.ts — use an existing module as a template
  2. Export a PluginDefinition with a unique id, category, and all required manifest fields
  3. Add the export to packages/modules/src/index.ts
  4. Add the import and entry to BUILTIN_MODULES in packages/modules/src/registry-loader.ts
  5. Add the selection → module ID mapping to SELECTION_TO_MODULE_ID
  6. Add a prompt choice to the appropriate array in packages/cli/src/prompt/graph-definition.ts

Clone this wiki locally