Mosaik

Create React, Express, and NestJS projects with the tools you choose.

Mosaik is a modular project scaffolding CLI. Pick a framework, JavaScript or TypeScript where available, and compatible plugins. Mosaik copies the starter files, adds plugin configuration, installs dependencies, and gives you a project you can run and edit.

This guide covers 1.1.0, including the create, add, and doctor commands.

Requirements

• Node.js 22 or later.
• Your chosen package manager installed: npm, pnpm, Yarn, or Bun.
• Git available for project initialization.
• Internet access to download the CLI and your project's dependencies.

You do not need to clone the Mosaik repository or install the CLI globally.

Quick start

npx create-mosaik@latest create my-app
cd my-app
npm run dev

Choose npm in the prompts for the example above. If you select pnpm, Yarn, or Bun, start the project with pnpm run dev, yarn run dev, or bun run dev instead.

The prompts let you select a generator, package manager, and compatible plugins. Where supported, you can choose a database separately. Plugin selection is optional: start with a minimal project and add compatible shipped plugins later.

You can also omit the project name and enter it interactively:

npx create-mosaik@latest create

To use this specific release, replace @latest with @1.1.0.

Commands

| Command | What it does | | --- | --- | | npx create-mosaik@latest create [name] | Create a project through interactive prompts. | | npx create-mosaik@latest add [plugin-id] | Add a compatible shipped plugin to an existing Mosaik project. | | npx create-mosaik@latest doctor | Check an existing Mosaik project without changing files. | | npx create-mosaik@latest --help | Show available commands. | | npx create-mosaik@latest --version | Show the CLI version. |

Add a plugin

Run add from your generated project's root, alongside its package.json and .mosaik/ folder. For example, add Axios to a React project:

npx create-mosaik@latest add axios

Or choose a plugin interactively:

npx create-mosaik@latest add

Mosaik checks the generator and the complete plugin selection for compatibility, applies the plugin, installs dependencies using the project's recorded package manager, and updates the project manifest. Adding a plugin already recorded in the manifest is a successful no-op.

Plugins can edit existing files. Review or commit your work before applying one. If dependency installation fails, plugin files and package.json edits may remain; Mosaik updates its project manifest only after installation succeeds. Automatic rollback is not available.

Check project health

npx create-mosaik@latest doctor

doctor checks project JSON files, the recorded generator and plugins, compatibility, Node.js support, and package-manager availability. It collects diagnostics and reports passes, warnings, and errors together. Errors produce a nonzero exit code; warnings alone do not. It never fixes or rewrites your files.

An older recorded generator version may produce a warning after a CLI update. That warning does not mean the project was upgraded. doctor does not compile your application, audit dependencies, or test external services.

Supported project types

| Generator | Starter | | --- | --- | | react-ts | React + TypeScript, built with Vite. | | react-js | React + JavaScript, built with Vite. | | express-ts | Express + TypeScript, with routes, controllers, services, middleware, and configuration folders. | | express-js | Express + JavaScript, with the same backend folder layout. | | nest-ts | NestJS + TypeScript, using Nest's CommonJS and decorator conventions. |

Every starter provides a dev script. React starters also provide build and preview; Express TypeScript and NestJS provide build and start; Express JavaScript provides start and runs without a TypeScript build step.

Included plugins

Mosaik ships 35 plugins. The interactive picker only offers plugins compatible with the chosen generator. Compatibility also includes relationships between plugins, so not every combination is valid. The linked documentation explains each plugin's dependencies, requirements, and conflicts.

React JavaScript and TypeScript

| Plugin id | What it adds | | --- | --- | | axios | Axios and a configured API client. | | eslint | Flat-config ESLint, with TypeScript support when appropriate. | | heroui | HeroUI components and provider setup. | | icons | The Lucide React icon library. | | react-hook-form | Form handling and an example form component. | | react-router | Routing and an example second page. | | redux-toolkit | Redux Toolkit and React Redux state management. | | tailwind | Tailwind CSS with Vite integration. | | tanstack-query | TanStack Query, a query client, and its React provider. | | zustand | Zustand state management and an example store. |

Express TypeScript

| Plugin id | What it adds | | --- | --- | | bcrypt | Password hashing and comparison helpers. | | cors | CORS middleware configuration. | | date-fns | Date utility functions as a dependency. | | dotenv | Environment variable loading at startup. | | firebase-admin | Firebase Admin SDK initialization. | | google-apis | Google APIs and an OAuth2 client. | | http-client | A configured Axios client for backend requests. | | jwt-auth | JWT signing/verification helpers and authentication middleware. | | mongodb | Mongoose for MongoDB. | | node-cron | Scheduling support and an example job. | | nodemailer | A configured SMTP mail transporter. | | otp-generator | An OTP generation dependency. | | postgres-drizzle | Drizzle ORM and PostgreSQL tooling. | | postgres-prisma | Prisma ORM configured for PostgreSQL. | | randomstring | A random-string generation dependency. | | redis | A Redis client. | | s3-storage | S3 upload support using the AWS SDK and multer-s3. | | stripe | A configured Stripe client. | | swagger | OpenAPI documentation for Express. | | ua-parser-js | A User-Agent parsing helper. | | uuid | A UUID generation dependency. | | zod | Schema validation and an example schema. |

These backend integrations currently target Express TypeScript, not Express JavaScript or NestJS. Database and service plugins provide starter code; configure your own service endpoints, environment variables, and credentials before using them.

NestJS

| Plugin id | What it adds | | --- | --- | | nest-swagger | NestJS OpenAPI/Swagger integration. |

All five project types

| Plugin id | What it adds | | --- | --- | | docker | A Dockerfile and .dockerignore matched to the starter. | | prettier | Prettier formatting configuration, with ESLint integration when applicable. |

Browse detailed plugin documentation.

How Mosaik works

1. Choose a generator. It defines the framework, language, and project creation steps.
2. Choose compatible plugins. Mosaik validates their requirements and installation order.
3. Generate starter files. Templates provide your application's initial files and structure.
4. Apply plugins and install dependencies. Plugins add packages, configuration, and starter code.
5. Record the project and initialize Git. .mosaik/project.json records the CLI version, generator and version, selected plugin ids, package manager, and creation time.

Keep .mosaik/project.json: add and doctor use it to understand your project. Your generated application runs through its own package scripts; you can edit its files normally without running Mosaik as an application service.

Internally, generators, templates, and plugins are separate packages discovered through manifests. The CLI bundles access to its shipped packages. Installing an arbitrary third-party plugin package does not automatically make it available to add.

Troubleshooting

• Node version error: use Node.js 22 or later, then retry.
• Package manager unavailable: install the manager you selected and make sure it is on your PATH.
• Missing project manifest: run add or doctor from a Mosaik-generated project root.
• Plugin unavailable or incompatible: check its supported generator and plugin requirements.
• Install or service setup failure: review the reported error and generated configuration. Run doctor for project metadata and environment checks.

Documentation and support

• Source code
• Generators
• Plugins
• Contributing
• Report an issue

License

MIT