coreseed-cli

npm: coreseed-cli · Source on GitLab

coreseed-cli scaffolds a single-folder project with Django 6 and your choice of Vue 3 or React + Vite. Django exposes JSON APIs and serves an HTML shell; The selected frontend loads from Vite in development and from static assets when you build for production. The tool copies a bundled template, substitutes placeholders, and optionally creates a Python virtualenv, installs dependencies, runs migrations, and installs frontend packages.

Requirements

| Tool | Notes | | ---- | ----- | | Node.js | 18.18+ (also 20.9+ or 21.1+ per engines). Checked before work begins. | | npm | For npx / global install. Generated projects may use pnpm if you choose it. | | Python 3 | 3.12+ when setup runs (venv, pip, migrate). |

The target directory must be missing or empty.

Install and run

Try without installing globally (from the parent folder where the new project should appear):

npx coreseed-cli@latest my-app

Pin a version for reproducible runs:

npx [email protected] my-app

Global install:

npm install -g coreseed-cli
coreseed-cli my-app

Contributors (from a clone of this repo):

npm install
node index.mjs my-app

Quick start

Interactive (choose Quick for fewer prompts, or Custom for every option):

cd ~/projects
npx coreseed-cli@latest acme-portal

Non-interactive defaults (Vue + Element Plus, npm, default API URL, full setup unless skipped):

npx coreseed-cli@latest acme-portal --defaults

Scaffold only (no venv, pip, migrate, or frontend install):

npx coreseed-cli@latest acme-portal --defaults --skip-install

Command-line reference

coreseed-cli [project-directory] [options]

| Option | Description | | ------ | ----------- | | --template <dir> | Alternate template directory (resolved from cwd unless absolute). | | --defaults | Non-interactive: display name = directory name, API base http://127.0.0.1:8000, Vue + Element Plus, npm, full setup unless --skip-install. | | --skip-install | Skip venv, pip, migrations, frontend install, frontend build, and collectstatic. With interactive mode you still answer questions that affect generated files. | | --no-migrate | When setup runs: skip python manage.py migrate; frontend install, build, and collectstatic still run. | | -h, --help | Print usage. |

The project folder name becomes the directory on disk and feeds placeholders such as the project slug; the npm name field is derived as kebab-case.

Interactive wizard

Without --defaults:

1. Quick or Custom — Quick locks Vue + Element Plus, npm, the default API URL, SQLite, and no extra Django apps (only setup confirmation remains, unless --skip-install).
2. Custom path: database (SQLite or PostgreSQL), PostgreSQL connection details when selected, display name, Django API base URL, optional comma-separated Django app names, Vue 3 vs React, Vue state management (None / Pinia / Vuex) and optional Vue Router setup for Vue, a framework-specific UI library (Element Plus / Naive UI / PrimeVue for Vue; Material UI / Ant Design / None for React), npm vs pnpm, then whether to run setup (unless --skip-install).

Django app names must be valid Python identifiers, such as accounts, loans, reports. When setup runs, the CLI executes python manage.py startapp <name> for each name and adds the apps to INSTALLED_APPS. With --skip-install, create them manually after installing Python dependencies and add them to INSTALLED_APPS. When selected, Pinia or Vuex is registered in main.js, and Vue Router is created in src/router/index.js and registered in the app.

Canceling a prompt exits with failure.

What the CLI does (order)

1. Ensures Node version is supported.
2. Resolves the target directory and checks it is empty.
3. Runs the wizard (or applies defaults).
4. Copies the template (skips node_modules, variants, dist, venvs, etc.).
5. Applies the selected frontend variant (main.js/App.vue for Vue or main.jsx/App.jsx for React, plus vite.config.js and merged package.json deps).
6. Substitutes placeholders in a fixed list of files (see placeholders below).
7. If setup is enabled: creates venv, upgrades pip, and installs requirements.txt.
8. Runs Django startapp for each selected app, then runs npm/pnpm install and migrate in parallel (unless --no-migrate).
9. Runs npm/pnpm run build.
10. Runs Django collectstatic --noinput after the frontend build completes.
11. Prints the project path or manual next steps if setup was skipped.

Generated layout (typical)

After scaffolding (before install artifacts):

my-app/
├── .env.example
├── .gitignore
├── README.md
├── config.json
├── manage.py
├── requirements.txt
├── package.json
├── vite.config.js
├── index.html
├── public/
│   └── .gitkeep
├── templates/
│   └── base.html
├── core/
│   ├── __init__.py
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   ├── views.py
│   └── wsgi.py
└── src/
    ├── main.js
    └── App.vue

Vue projects also create src/assets/ (with fonts/, images/, main.css, and base.css), src/components/, src/composables/, src/constants/, src/layouts/, src/router/, src/stores/, and src/views/; PrimeVue projects additionally create src/ui/. React projects keep the simpler src/ layout.

Tailwind CSS is configured by default through the Vite plugin for every frontend variant. PrimeVue projects also include the tailwindcss-primeui integration.

The generated root scripts/ directory contains local-build.sh for rebuilding local static assets and deploy.sh for preparing and pushing a deployment commit.

After setup you may also see env/, db.sqlite3 (unless --no-migrate), node_modules/, a lockfile, dist/, and static/. The CLI runs the frontend build and then Django collectstatic automatically when setup is enabled.

config.json is a flat application configuration shared by Django and Vite. It includes DEBUG, HOST, PORT, DJANGO_PORT, DB_ENGINE, database settings, API_BASE_URL, and optional email/SMS settings. Custom setup asks whether to use SQLite or PostgreSQL; SQLite is the default for quick setup. It is returned as JSON from GET /api/config/ for the selected frontend app.

Running the generated project

1. Copy env: cp .env.example .env (optional; Vite can read VITE_API_BASE_URL; the app also loads /api/config/).

2. Backend (if you skipped setup):

   python3 -m venv env
   source env/bin/activate
   pip install -r requirements.txt
   python manage.py migrate
   python manage.py runserver

3. Frontend (second terminal): npm install then npm run dev (or pnpm).

4. Open http://127.0.0.1:8000/ so Django serves base.html, which loads the selected Vite frontend (default 5173) when DEBUG is true. DJANGO_PORT and PORT in config.json document the backend and frontend ports; pass DJANGO_PORT to runserver when using a non-default backend port. You can still use Vite alone with the root index.html if you configure the API proxy.

Production: npm run build, set DEBUG false, run collectstatic as needed, serve Django and static files per your host.

Placeholders

These tokens are replaced in a known set of project files (not in every file in the tree):

| Token | Meaning | | ----- | ------- | | __PACKAGE_NAME__ | Kebab-case npm name from the directory argument. | | __DISPLAY_NAME__ | Display / app title. | | __PROJECT_SLUG__ | Directory name you passed. | | __SECRET_KEY__ | Generated Django SECRET_KEY. | | __VITE_API_BASE__ | API origin for config.json / .env.example (no trailing slash). |

Custom templates should keep using these tokens in the same kinds of files, or extend the CLI’s allowlist if you fork it.

Publishing (maintainers)

1. Bump version in package.json, update CHANGELOG.md, and commit.
2. Verify pack contents: npm pack --dry-run
3. Run tests: npm test and node scripts/verify-template.mjs
4. Log in once: npm login
5. Publish: npm publish (use npm publish --access public if the package is scoped and should be public)

Ensure you have rights to the coreseed-cli package on npm. If npm publish warns about bin, run npm pkg fix locally and release a patch version.

Developing this CLI

npm test
node scripts/verify-template.mjs

License

MIT