`@push-based/create-ngp`: scaffold an Angular app on vite-plugin-ngp, for `vp create @push-based/ngp` and `npm create @push-based/ngp`

Open
  • Is something wrong?
#14 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
angular, node.js, typescript, vite
Domain
build-system, cli, testing

Research direction

Read the Getting started and Testing pages, the Server rendering page, and packages/vite-plugin-ngp/package.json plus toolchain/versions.env for the template details and pinned versions. Start by checking the create-vite argument and scaffold patterns, then build both templates under packages/create-ngp/templates/ and add the listed unit and integration coverage. Done means each template scaffolds successfully and the specified build, test, SSR, and available Vite+ checks pass.

Written by the indexing model from the issue text.

Description

feature

Part of #13. Labels: feature.

What a user does

vp create @push-based/ngp my-app          # Vite+
npm create @push-based/ngp@latest my-app  # npm
pnpm create @push-based/ngp my-app        # pnpm

Then cd my-app and vp dev (or pnpm dev). The app is the one Getting started describes, generated instead of typed.

Behaviour

Arguments and flags (parse with mri, like create-vite):
[directory] Target. Prompted ("Project name:", default ngp-app) when absent and interactive
-t, --template <app|app-ssr> Template. Prompted when absent and interactive. Default app when non-interactive
--overwrite Empty a non-empty target without asking. Without it, interactive asks; non-interactive aborts
--interactive / --no-interactive Default process.stdin.isTTY
-h, --help

No --immediate, no git init, no install. Vite+ does install, git, hooks and formatting itself after the template exits, and a second git init is what create-analog gets wrong. Print "Done. Now run:" with cd, <pm> install, <pm> dev, where <pm> comes from npm_config_user_agent. Under vp the install line is harmless because vp installs right after.

Remember that vp does not prepend the target directory and does not forward --no-interactive; vp create @push-based/ngp -- --no-interactive --template app is the unattended form, and the docs show it.

Templates, as packages/create-ngp/templates/<name>/, copied file by file, with _gitignore → .gitignore, package.json#name set to the valid package name derived from the directory, and <title> in index.html replaced. Nothing else is templated: no placeholders, no engine.

  • app: index.html, vite.config.ts (defineConfig from vite, ngp() with no options), tsconfig.json + tsconfig.app.json + tsconfig.spec.json as ng new writes them, src/main.ts, src/app/app.ts + app.html + app.css, app.config.ts with provideRouter, routes.ts with one route, src/styles.css, src/app/app.spec.ts, src/test-setup.ts, vitest.config.ts per the Testing page, public/favicon.svg, README.md, _gitignore. package.json scripts: dev, build, preview, test. Dependencies: the exact pins from Getting started (@angular/* at the plugin's pinned version, typescript 6.0.3, vite 8.3.4, vitest, jsdom, the plugin at the version released alongside).
  • app-ssr: app plus src/main.server.ts (the Server rendering page's entry, allowedHosts: ['localhost']), provideClientHydration(withEventReplay()) in app.config.ts, ngp({ssr: true}), server.mjs copied from the playground, and a start script.

The pinned versions come from one place: a versions.json that the build writes from packages/vite-plugin-ngp/package.json and toolchain/versions.env, so a plugin release can't ship a template pinned to an older Angular.

Vite+ handling. The output is a plain Vite project. vite is in devDependencies so that vp's post-create rewrite aliases it to @voidzero-dev/vite-plus-core; without that line the plugin can't load under vp (see the epic). Verify in a test that after vp create @push-based/ngp, vp build, vp test run and vp check --fix && vp check all pass. If vp's injected fmt: {} formats Angular sources to double quotes, add fmt: {singleQuote: true} to the template config; vp keeps a template's own fmt/lint keys.

Tests

  • Unit: argument parsing, package-name derivation, overwrite rules, the rename map.
  • Integration (node --test, like the plugin): scaffold each template into a temp dir, pnpm install with the workspace plugin linked, vite build, vitest run. For app-ssr, also node server.mjs and fetch /.
  • Under Vite+: the same, through vp create ./packages/create-ngp -- --no-interactive, when vp is on PATH; skipped otherwise. CI installs vite-plus in that job.

Docs

Covered by the docs sub-issue; this issue is done when the package scaffolds both templates and the tests above pass.

Out of scope

Tailwind, Angular Material, i18n, Nx workspaces, --immediate, an ng new-compatible flag set.

Dominant language
TypeScript
Stars
7
Forks
1
Avg merge
12h 24m
Merged PRs (30d)
13

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from push-based/vite-plugin-ngp

All issues in push-based/vite-plugin-ngp

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.