@papit/create 0.0.11 → 0.0.12

package/README.md

@@ -1,17 +1,9 @@
 # @papit/create
 
-Project and package scaffolding tool for @papit — opinionated, consistent, and designed to kickstart Papit-based projects with the correct structure from day one.
+Scaffolds papit packages, components and monorepo projects from templates, interactively or through flags. Run it inside a papit workspace to add a package or component, or outside one to start a new project.
 
 ![Logo](https://raw.githubusercontent.com/onkelhoy/papit/refs/heads/main/asset/logo.svg)
 
-This package is intended to be used **from within a workspace or an empty directory**. Simply run:
-
-```bash
-npm create @papit
-```
-
-to generate a fully initialized Papit package, component, or project with zero or minimal configuration.
-
 ---
 
 ![Type](https://img.shields.io/badge/Type-cli-orange)
@@ -20,154 +12,216 @@ to generate a fully initialized Papit package, component, or project with zero o
 
 ---
 
-## CLI Flags
+# Installation
 
-| Flag          | Description                         |
-| ------------- | ----------------------------------- |
-| `--package`   | Create a package                    |
-| `--component` | Create a component                  |
-| `--project`   | Create a project                    |
-| `--agree`     | Skip confirmations                  |
-| `--install`   | Install dependencies after creation |
-| `--commit`    | Create an initial git commit        |
-| `--verbose`   | Show detailed output                |
+No install needed:
 
-If no creation flag is provided, an interactive selector is shown.
+```bash
+npm create @papit
+```
 
----
+It also installs as a dev dependency with the `papit-create` bin:
 
-## How it works
+```bash
+npm install -D @papit/create
+```
 
-`@papit/create` presents a set of creation options. Some of these can be invoked directly via flags, but the tool is primarily interactive and focused on generating boilerplate code based on predefined templates.
+# Usage
 
-There are currently three built-in runners:
+Pick a runner from a menu:
 
-1. `package`
-2. `component`
-3. `project`
+```bash
+npm create @papit
+```
 
-**Note:** You can provide your own custom runners by placing them in the `bin` folder. Each runner must have a `runner.js` file with a default export, for example:
+Go straight to a runner (npm needs the `--` to pass the flags on):
 
-```
-<workspace-root>/bin/runners/<custom>/runner.js
+```bash
+npm create @papit -- --package
+npm create @papit -- --component
+npm create @papit -- --project
 ```
 
-A runner is a function that receives two arguments:
+The papit repo root wires it up as `npm run create`:
 
-```ts
-info: {
-  root: string; // Location of the workspace root
-  local: string; // Location of the current package (if any)
-  script: string | null; // Location of the @papit/create script
+```json
+{
+  "scripts": {
+    "create": "npm create @papit -- --package --html-prefix=pap"
+  }
 }
 ```
 
-```ts
-args: {
-  flags: Record<string, string | string[] | true | undefined>,
-  values: string[]
-}
+Fully non-interactive, from inside a workspace:
+
+```bash
+npm create @papit -- --package=node --name=my-tool --description="Does a thing." --agree
 ```
 
-For more details on the structure and behavior of these arguments, see the
+The folder under `packages/` is still picked from a menu.
 
-- `@papit/arguments`
-- `@papit/information`
-  package.
+Outside a papit workspace, it always runs the project runner.
 
----
+# CLI flags
 
-## Package
+| Flag | Runner | Description |
+| --- | --- | --- |
+| `--package[=<template>]` | all | Run the package runner. With a value, it's the template too (`browser`, `game`, `node`, `theme`, `web-component` or a custom one). |
+| `--component` | all | Run the component runner. |
+| `--project` | all | Run the project runner. |
+| `--showcase` | all | Run the showcase runner (experimental, see below). |
+| `--<custom>` | all | Run a custom runner from `bin/runners/<custom>/`. |
+| `--type=<template>` | package, component | Template to use, when `--package` has no value. |
+| `--name=<name>` | package, component, project | Name. Spaces and `-` separate words: `my button` becomes `my-button` / `MyButton`. |
+| `--description=<text>` | package, project | Description for `package.json` and the README. |
+| `--html-prefix=<prefix>` | package, component, showcase | Tag prefix for web components (`pap` gives `pap-<name>`). Falls back to the package's then the root's `papit.htmlprefix`, otherwise prompts. |
+| `--agree` | package, component | Yes to everything: folder creation, git commit and `npm install`. |
+| `--commit` | package, component | Commit the result without asking. |
+| `--install` | package | Run `npm install` without asking. |
+| `--yes` / `--no` | package | Answer the commit and install questions. |
+| `--location=<path>` | project | Where to create the project. Default: prompted, then `<path>/<name>`. |
+| `--license=<id>` | project | License for the generated `package.json`s. Default `MIT`. |
+| `--skip-git` | project | Don't `git init` and commit. |
+| `--verbose`, `--debug` | all | Log levels, see [@papit/arguments](https://github.com/onkelhoy/papit/tree/main/packages/runtime/cli/arguments). |
 
-The **package runner** creates a new package at a selected location (sometimes referred to as layers or folders).
+# Runners
 
-A template is selected — either one of the built-in templates or a custom template located at:
+## package
 
-```
-<workspace-root>/bin/runners/package/*
-```
+1. Pick or create a folder under `packages/` (`--agree` skips the creation confirm).
+2. Pick a template, unless `--package=<template>` or `--type` names one.
+3. For a web component, settle the html prefix. When the root has none, it offers to save yours as the root's `papit.htmlprefix`.
+4. Ask for name and description. The name must not already exist in the workspace (`<scope>/<name>`).
+5. Copy the template into `<folder>/<name>` and replace the [template variables](#template-variables). `.gitkeep` files are dropped.
+6. Run the component runner for a first component with the package's own name, using the component template of the same type.
+7. Install and commit (`add: <scope>/<name> package`), when agreed.
 
-The selected template folder is copied, and all files are processed to replace supported variables.
+## component
 
-The generated license file automatically references the same license as the workspace root.
+Adds a component to the package you're in. The template is the package's `papit.type`, then `--package` / `--type`, otherwise prompted. It registers the component under `papit.components` in the package's `package.json`, then copies each top-level template folder:
 
-### Available variables
+| Template folder | Goes to |
+| --- | --- |
+| `src` | `src/` when it's empty, otherwise `src/components/<name>/` |
+| `tests`, `views`, others | `<folder>/<name>/` |
 
-- `VARIABLE_NAME`
-- `VARIABLE_FULL_NAME`
-- `VARIABLE_DESCRIPTION`
-- `VARIABLE_LAYER_FOLDER`
-- `VARIABLE_PROJECTLICENSE`
-- `VARIABLE_GITHUB_REPO`
-- `VARIABLE_LOCAL_DESTINATION`
-- `VARIABLE_CLASS_NAME`
-- `VARIABLE_HTML_PREFIX`
-- `VARIABLE_USER`
+The first component of a new package lands directly in `src/` and in `views/experiment/`. Commits as `add: <name> component` when agreed.
 
----
+## project
 
-## Component
+Creates a new papit monorepo from the [project template](#project-template): prompts for name, description and location, asks before replacing an existing folder, copies the template, then `git init`, commits (`init: <name> initialized`) and runs `npm install`. The root package is named `@<name>/root`.
 
-The **component runner** creates a new component and is intended for adding sub-components to an existing package.
+## showcase
 
-Like the package runner, it copies a selected template from either built-ins or:
+Experimental. For every `web-component`, `game` and `theme` package in the workspace whose first view isn't `views/showcase`, it generates one from `asset/showcase-templates/individual`, with a tab per existing view (`--view-filter`, default `showcase`, `raw`, `experiment`).
 
-```
-<workspace-root>/bin/runners/component/*
+## Custom runners
+
+Any folder in `<workspace-root>/bin/runners/` with a `runner.js` becomes a runner, listed in the menu and selectable as `--<folder>`. The names `package`, `component`, `project` and `showcase` are taken.
+
+```js
+// bin/runners/release-notes/runner.js
+import { Arguments } from "@papit/arguments";
+import { Information } from "@papit/information";
+
+export default async function () {
+    console.log(Information.root.location, Arguments.string("since"));
+}
 ```
 
-### Folder handling
+The default export is called with no arguments. Read flags and the workspace through [@papit/arguments](https://github.com/onkelhoy/papit/tree/main/packages/runtime/cli/arguments) and [@papit/information](https://github.com/onkelhoy/papit/tree/main/packages/runtime/cli/information).
 
-- **views**
-  If a `views` folder exists in both the current package and the template, a new subfolder named after the component is created inside the package’s `views` directory and populated with the template content.
+## Custom templates
 
-- **src**
-  If the current package already has a `src` folder with files, the template’s `src` content is typically placed under:
+| Location | Requirement |
+| --- | --- |
+| `bin/runners/package/<template>/` | Must contain a `package.json`. |
+| `bin/runners/component/<template>/` | Top-level folders are copied as in the [component runner](#component). |
 
-  ```
-  src/components/<component-name>
-  ```
+They're listed next to the built-in ones and selected by name. The project runner has no custom templates.
 
-### Available variables
+# Package templates
 
-- `VARIABLE_NAME`
-- `VARIABLE_FULL_NAME`
-- `VARIABLE_HTML_NAME`
-- `VARIABLE_CLASS_NAME`
+Every package template has `package.json`, `README.md`, `tsconfig.json`, `tsconfig.prod.json`, `.gitignore` and `asset/translations/en.json`. Scripts include `build` (`npx @papit/build`), `test`, `start` and `component`.
 
----
+| Template | `papit.type` | Gets |
+| --- | --- | --- |
+| `browser` | `browser` | Playwright tests, `asset/icons`, `asset/images`. |
+| `game` | `game` | Playwright tests, `views/`, `asset/models`, `asset/textures`. |
+| `node` | `node` | `node:test` tests (`npm test`, `npm run test:only`), `npm start` builds and runs `lib/bundle.js`. |
+| `theme` | `theme` | Ships `lib/theme.css` as the package export. Playwright tests. No build script. |
+| `web-component` | `web-component` | Playwright tests, `views/`, `@papit/web-component` as a dependency, `papit.htmlprefix`. |
 
-## Project
+## web-component
 
-> ⚠️ This runner is currently under development.
+On top of the above, a web component package gets:
 
-The **project runner** creates a raw monorepo project at a selected destination.
+- `"analyse": "npx @papit/analyse"`, which writes `analyse.json` (see [@papit/analyse](https://github.com/onkelhoy/papit/tree/main/packages/runtime/cli/analyse))
+- `"generate:react": "npx @papit/react"`, which writes `src/react-wrapper.tsx` (see [@papit/react](https://github.com/onkelhoy/papit/tree/main/packages/runtime/cli/react))
+- `react` `^19` as an optional peerDependency, tsconfig `"jsx": "react-jsx"` and `paths` mapping the package's own name to `./index`
 
-As with packages and components, custom templates can be provided at:
+The `./react` export isn't in the template. Add it by hand once `src/react-wrapper.tsx` has been generated, so the import path is `@papit/<name>/react`:
 
-```
-<workspace-root>/bin/runners/project/*
+```json
+"./react": { "import": "./lib/react-wrapper.js", "types": "./lib/react-wrapper.d.ts" }
 ```
 
-You will be prompted to select a template during creation.
+Without the file, `@papit/bundle-js` would build that entry from `src/index.ts` instead.
 
-Licensing is handled interactively. You may provide an existing license file or omit it, in which case a standard MIT license is used.
+# Component templates
 
-### Available variables
+One per package type, each filled in with the component's name:
 
-- `VARIABLE_NAME`
-- `VARIABLE_DESCRIPTION`
-- `VARIABLE_PROJECTLICENSE`
-- `VARIABLE_USER`
+| Template | `src` | `tests` | `views` |
+| --- | --- | --- | --- |
+| `browser` | `component.ts`, `index.ts`, `types.ts` | Playwright `unit.test.ts`, `snapshot.test.ts`, test page | demo page |
+| `game` | `component.ts`, `index.ts`, `types.ts` | Playwright `unit.test.ts`, `snapshot.test.ts`, test page | demo page |
+| `node` | `component.ts`, `index.ts`, `types.ts` | `unit.test.js` | none |
+| `theme` | `theme.css` | Playwright `unit.test.ts`, `snapshot.test.ts`, test page | demo page |
+| `web-component` | a `CustomElement` class, `style.css`, `types.ts`, `index.ts` that defines `<prefix>-<name>` | Playwright `unit.test.ts`, `snapshot.test.ts`, test page | demo page |
 
----
+# Project template
 
-## License
+A root `package.json` with npm workspaces (`packages/**/*`, excluding `asset/` folders) and these scripts:
+
+| Script | Runs |
+| --- | --- |
+| `analyse` | Every workspace's `analyse` script (`npm run analyse --workspaces --if-present`). |
+| `build` | `npx @papit/build` |
+| `test` | `node bin/test.mjs`, every package's `npm test`. |
+| `start` | `npx @papit/server --serve --info` |
+| `create` | `npm create @papit -- --package` |
+| `clean` | `node bin/clean.mjs` |
+| `version:reset`, `version:sync` | `npx @papit/version --reset` / `--sync` |
+
+devDependencies: `@papit/build`, `@papit/bundle-js`, `@papit/bundle-ts`, `@papit/server`, `@papit/create`, `@papit/version`, `@papit/arguments`, `@papit/terminal`, `@papit/information`, `@papit/analyse`, `@papit/react`, `esbuild` and `typescript`. A project that uses `generate:react` adds `react` and `@types/react` as root devDependencies itself.
+
+Also included: `.gitignore` (ignores `packages/**/lib/` and the generated `packages/**/analyse.json`), GitHub workflows for pull requests and publishing, `.vscode` settings, `.nvmrc`, `bin/` helpers and an example custom runner in `bin/runners/example-runner/`.
+
+# Template variables
+
+Replaced in every copied file.
+
+| Variable | Package | Component | Project | Value |
+| --- | :-: | :-: | :-: | --- |
+| `VARIABLE_NAME` | ✓ | ✓ | ✓ | Kebab-case name. Project: `@<name>/root`. |
+| `VARIABLE_FULL_NAME` | ✓ | ✓ | | `<scope>/<name>`. Component: the package's name. |
+| `VARIABLE_CLASS_NAME` | ✓ | ✓ | | PascalCase name. |
+| `VARIABLE_HTML_NAME` | ✓ | ✓ | | `<prefix>-<name>` |
+| `VARIABLE_HTML_PREFIX` | ✓ | | | The html prefix, or empty. |
+| `VARIABLE_DESCRIPTION` | ✓ | | ✓ | The description. |
+| `VARIABLE_LAYER_FOLDER` | ✓ | | | Name of the folder the package goes in, e.g. `atoms`. |
+| `VARIABLE_LOCAL_DESTINATION` | ✓ | | | Package path from the workspace root. |
+| `VARIABLE_GITHUB_REPO` | ✓ | | | Root `repository.url` without `git+` and `.git`. |
+| `VARIABLE_PROJECTLICENSE` | ✓ | | ✓ | Root `license` (default `MIT`). Project: `--license`. |
+| `VARIABLE_USER` | ✓ | | ✓ | `$USER`, prompted when unset. |
+
+# License
 
 Licensed under the **@Papit License 1.0**
 Copyright (c) 2024 Henry Pap (@onkelhoy)
 
-**Key points:**
+**Key points**
 
 - ✅ Free to use in commercial projects
 - ✅ Free to modify and distribute
@@ -175,3 +229,18 @@ Copyright (c) 2024 Henry Pap (@onkelhoy)
 - ❌ Cannot resell the component itself as a standalone product
 
 See the [LICENSE](https://github.com/onkelhoy/papit/blob/main/LICENSE) file for full details.
+
+---
+
+# Related
+
+- [@papit/information](https://github.com/onkelhoy/papit/tree/main/packages/runtime/cli/information)
+  Finds the workspace root, its scope and existing packages.
+- [@papit/arguments](https://github.com/onkelhoy/papit/tree/main/packages/runtime/cli/arguments)
+  Parses the flags.
+- [@papit/build](https://github.com/onkelhoy/papit/tree/main/packages/runtime/cli/build)
+  Builds the packages it creates.
+- [@papit/analyse](https://github.com/onkelhoy/papit/tree/main/packages/runtime/cli/analyse)
+  Behind the web component template's `analyse` script.
+- [@papit/react](https://github.com/onkelhoy/papit/tree/main/packages/runtime/cli/react)
+  Behind the web component template's `generate:react` script.

package/asset/package-templates/web-component/package.json

@@ -10,6 +10,8 @@
     "version": "0.0.1",
     "scripts": {
         "build": "npx @papit/build --error",
+        "analyse": "npx @papit/analyse",
+        "generate:react": "npx @papit/react",
         "watch": "tsc -w",
         "start": "npx @papit/server --info --live",
         "test": "npx playwright test -c tests/playwright.config.ts $@",
@@ -17,8 +19,7 @@
         "postversion": "papit-version",
         "component": "npm create @papit --component",
         "test:update-snapshots": "npx playwright test --update-snapshots -c tests/playwright.config.ts",
-        "test:chrome": "npm test -- --project=chromium",
-        "build:react": "bash ./bin/_utils/react.sh"
+        "test:chrome": "npm test -- --project=chromium"
     },
     "main": "./lib/bundle.js",
     "types": "./lib/bundle.d.ts",
@@ -56,6 +57,14 @@
     "dependencies": {
         "@papit/web-component": "*"
     },
+    "peerDependencies": {
+        "react": "^19"
+    },
+    "peerDependenciesMeta": {
+        "react": {
+            "optional": true
+        }
+    },
     "devDependencies": {
         "@playwright/test": "1.58.0",
         "playwright": "1.58.0",

package/asset/project-template/package.json

@@ -4,7 +4,7 @@
     "description": "VARIABLE_DESCRIPTION",
     "private": true,
     "scripts": {
-        "analyse": "to come",
+        "analyse": "npm run analyse --workspaces --if-present",
         "publish": "to come",
         "clean": "node bin/clean.mjs",
         "build": "npx @papit/build",
@@ -39,7 +39,9 @@
         "@papit/build": "*",
         "@papit/server": "*",
         "@papit/create": "*",
-        "@papit/version": "*"
+        "@papit/version": "*",
+        "@papit/analyse": "*",
+        "@papit/react": "*"
     },
     "papit": {}
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@papit/create",
-  "description": "",
-  "version": "0.0.11",
+  "description": "Scaffolds papit packages, components and monorepo projects from templates, interactively or through flags. Run it inside a papit workspace to add a package or component, or outside one to start a new project.",
+  "version": "0.0.12",
   "scripts": {
     "build": "npx @papit/build -- --error --ancestors",
     "watch": "tsc -w",
@@ -49,8 +49,8 @@
   },
   "dependencies": {
     "@papit/arguments": "0.0.1",
-    "@papit/information": "0.0.8",
-    "@papit/server": "1.0.7",
+    "@papit/information": "0.0.9",
+    "@papit/server": "1.0.8",
     "@papit/terminal": "0.0.2"
   },
   "devDependencies": {
@@ -58,8 +58,15 @@
     "typescript": "5.9.3"
   },
   "keywords": [
+    "papit",
+    "cli",
     "node",
-    "typescript"
+    "typescript",
+    "create",
+    "scaffolding",
+    "templates",
+    "monorepo",
+    "web-component"
   ],
   "papit": {
     "publish": true,
@@ -70,5 +77,5 @@
     },
     "components": {}
   },
-  "remoteVersion": "0.0.10"
+  "remoteVersion": "0.0.11"
 }