Description

@appweaver/create generates a ready-to-run Appweaver project for Node or Bun: the source layout, configuration files per environment, a seeded admin user, the test setup, the agent skill files for the chosen AI agent, and the optional modules (Redis, queue, scheduler, mailer, templates, locales, Docker files). It also creates module packages, the drivers and features published to npm.

Usage

npm create @appweaver <name> [description] -- [options]
npx @appweaver/create <name> [description] [options]

npm create @appweaver MyApp "My awesome API" -- --database postgresql --add redis queue docker
npx @appweaver/create MyApp "My awesome API" --all --exclude scheduler
npx @appweaver/create Reports "Nightly reports" --add scheduler --exclude web   # a database worker, no server
npx @appweaver/create Calculator "A calculator" --exclude data web              # the core application alone

npm passes the options after -- to the create-appweaver binary, npx takes them directly.

| Flag | Description | Default | |--------------------------|-----------------------------------------------------------------------------------|--------------| | --add <modules...> | Modules to add to the default ones, separated by spaces or commas | data web | | --all | Add every module | false | | --exclude <modules...> | Modules to leave out of the default ones or of --all, by spaces or commas | none | | -o, --output-dir <dir> | Output directory (use ./ for current working directory) | project name | | --database <type> | sqlite, postgresql, mysql, sqlserver, the database of data | sqlite | | --host <host> | Hostname or IP address the server of web binds to | 0.0.0.0 | | --port <port> | Port number the server of web listens on | 5000 | | --bun | Use Bun as the application runtime | Node | | --agent <agent> | claude, codex, junie, cursor, copilot, opencode, kiro, pi, none | claude | | --no-install | Skip the installation of the dependencies | installs |

The base project depends only on @appweaver/cli, @appweaver/common, @appweaver/core and TypeBox, a minimal application without a database or a server, and data and web are added to it by default, making a web API. --exclude leaves out any module, the default ones included and without --all: --exclude web keeps the database without a server, --exclude data web the core application alone (web requires data, so excluding data alone is refused). A module installs its packages, and a module required by an added one is added along with it:

| Module | Adds | Without it | |------------------|----------------------------------------------------------------------------------------------------------------|---------------------------------------------| | data (default) | @appweaver/data, @appweaver/sharp, Prisma, database/, the generated types, the test database | no database | | web (default) | @appweaver/web, requires data, the server config, the User auth resource, its admin seeder and public/ | no HTTP server, no auth model | | redis | @appweaver/redis, the Redis connection, the Redis service of docker-compose.yml | memory, cache and rate limit in the process | | queue | @appweaver/bullmq, requires redis | in-memory queue | | scheduler | @appweaver/cron | scheduler disabled | | mailer | @appweaver/nodemailer, the account email templates with templates, their texts with locales | mailer disabled | | templates | @appweaver/handlebars and templates/ | no template engine | | locales | locales/en.json, empty without the mailer | English texts written into the templates | | docker | Dockerfile, .dockerignore, docker-compose.yml, start.sh | no Docker files |

The modules of an existing project are managed with the weaver CLI, from the same templates:

npx weaver module list
npx weaver module add templates locales
npx weaver module remove docker

With data, create the first migration and seed the database:

cd my-app
npx weaver migration new init
npm run seed
npm run dev

Module packages

npm create @appweaver module <package> [description] -- [options]

npm create @appweaver module @acme/appweaver-gcs "Google Cloud Storage driver" -- --contract storage
npx @appweaver/create module @acme/appweaver-audit

| Flag | Description | Default | |--------------------------|-------------------------------------------------------------------------------|--------------------------------| | -o, --output-dir <dir> | Output directory | package name without its scope | | --contract <contract> | The contract its driver implements: storage, mailer, none for a feature | none |

The package is a module enabled by installing it: its package.json has the appweaver.module field and the appweaver-module keyword, with @appweaver/common and @appweaver/core as peer dependencies. It holds the manifest (src/module.ts), a config section (src/config.ts), and either a driver class (GcsStorage, <Name>Mailer) with a test running the contract suite of @appweaver/testing, or the startup code of a feature module (src/main.ts), with the TypeScript and Jest setup. The short name, without the scope and the appweaver- prefix (gcs), is the name of its provider and of its config section (storage.gcs for a storage driver).

cd appweaver-gcs
npm install
npm test
npm publish

An application then adds it with weaver module add @acme/appweaver-gcs.

Documentation

• Appweaver README – getting started, configuration, and the overview of every package
• Agent skill – the complete framework reference shipped to every scaffolded project

License

Appweaver is MIT licensed.