Skip to content

Commit 04f870e

Browse files
PAMulliganclaude
PAMulligan
and
claude
committed
feat: add create-claudius project scaffolder
`npm create claudius@latest` scaffolds a ready-to-run Claudius project (vanilla, React, or Next.js), optionally with a Cloudflare Worker — the same way `npm create vite` works. - create-claudius/ — CLI (@clack/prompts + node:util parseArgs) that copies a template with token replacement; every prompt has a flag for non-interactive use. - Templates: vanilla (CDN script embed), react (Vite + claudius-chat-widget), next (App Router + 'use client' wrapper), and an optional config-first worker scaffold (wrangler.toml + KV stub + deploy runbook). - Snapshot tests of generated output for every template (vitest). - Version-synced with the widget via release-please; auto-publishes on release, and the manual publish-npm workflow now selects which package to publish. - CI job (typecheck + test + build); docs scaffolding page + sidebar entry; README badge + quick-start section. Verified: all three frameworks install and build against the published claudius-chat-widget@1.6.0, the worker scaffold typechecks, and the npm tarball ships dist + templates (including dotfiles). Closes #42 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 3f857d1 commit 04f870e

47 files changed

Lines changed: 3724 additions & 12 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,3 +75,34 @@ jobs:
7575

7676
- name: Test (Vitest)
7777
run: pnpm test
78+
79+
create-claudius:
80+
name: Validate create-claudius
81+
runs-on: ubuntu-latest
82+
defaults:
83+
run:
84+
working-directory: create-claudius
85+
steps:
86+
- uses: actions/checkout@v4
87+
88+
- uses: pnpm/action-setup@v4
89+
with:
90+
version: 9
91+
92+
- uses: actions/setup-node@v4
93+
with:
94+
node-version: 20
95+
cache: pnpm
96+
cache-dependency-path: create-claudius/pnpm-lock.yaml
97+
98+
- name: Install dependencies
99+
run: pnpm install --frozen-lockfile
100+
101+
- name: Type check
102+
run: pnpm typecheck
103+
104+
- name: Test (Vitest)
105+
run: pnpm test
106+
107+
- name: Build
108+
run: pnpm build

‎.github/workflows/publish-npm.yml‎

Lines changed: 18 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,27 @@
11
name: Publish to npm
22

3-
# Manual, on-demand publish of the widget to npm.
3+
# Manual, on-demand publish of a package to npm.
44
#
55
# The release-please workflow already publishes automatically when it cuts a
66
# release. This workflow exists for the cases that one can't handle:
7-
# - bootstrapping the very first publish (the release for the current version
8-
# already exists, so re-running release-please is a no-op), and
9-
# - recovering from a failed release publish without waiting for the next
10-
# release.
7+
# - bootstrapping the very first publish of a package (the release for the
8+
# current version already exists, so re-running release-please is a no-op), and
9+
# - recovering from a failed release publish without waiting for the next release.
1110
#
1211
# Requires the NPM_TOKEN secret to be an npm token that can publish the package
13-
# and bypasses 2FA (a classic Automation token, or a granular token with
14-
# "All packages" + read/write). Publishes with provenance (needs id-token).
12+
# (and create it on first publish) and bypasses 2FA — a granular token with
13+
# "All packages" + read/write, or an account-scoped token. Publishes with
14+
# provenance (needs id-token).
1515
on:
1616
workflow_dispatch:
1717
inputs:
18+
package:
19+
description: "Which package to publish"
20+
type: choice
21+
options:
22+
- widget
23+
- create-claudius
24+
default: widget
1825
dist-tag:
1926
description: "npm dist-tag to publish under"
2027
required: false
@@ -25,16 +32,16 @@ permissions:
2532
id-token: write # for npm provenance
2633

2734
concurrency:
28-
group: publish-npm
35+
group: publish-npm-${{ github.event.inputs.package }}
2936
cancel-in-progress: false
3037

3138
jobs:
3239
publish:
33-
name: Publish widget to npm
40+
name: Publish ${{ inputs.package }} to npm
3441
runs-on: ubuntu-latest
3542
defaults:
3643
run:
37-
working-directory: widget
44+
working-directory: ${{ inputs.package }}
3845
steps:
3946
- uses: actions/checkout@v4
4047

@@ -47,7 +54,7 @@ jobs:
4754
node-version: 20
4855
registry-url: https://registry.npmjs.org
4956
cache: pnpm
50-
cache-dependency-path: widget/pnpm-lock.yaml
57+
cache-dependency-path: ${{ inputs.package }}/pnpm-lock.yaml
5158

5259
- name: Install
5360
run: pnpm install --frozen-lockfile

‎.github/workflows/release-please.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,3 +103,13 @@ jobs:
103103
pnpm install --frozen-lockfile
104104
pnpm build
105105
npm publish --provenance --access public
106+
107+
- name: Build and publish create-claudius
108+
if: ${{ steps.release.outputs.release_created }}
109+
working-directory: create-claudius
110+
env:
111+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
112+
run: |
113+
pnpm install --frozen-lockfile
114+
pnpm build
115+
npm publish --provenance --access public

‎README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Claudius - Embeddable AI Chat Widget
22

33
[![npm](https://img.shields.io/npm/v/claudius-chat-widget.svg)](https://www.npmjs.com/package/claudius-chat-widget)
4+
[![create-claudius](https://img.shields.io/npm/v/create-claudius.svg?label=create-claudius)](https://www.npmjs.com/package/create-claudius)
45
[![license](https://img.shields.io/npm/l/claudius-chat-widget.svg)](LICENSE)
56

67
An open-source, embeddable AI chat widget powered by Claude. Drop it into any
@@ -16,6 +17,19 @@ website with a single script tag, or install it as a React component.
1617
Claudius is two pieces: a Cloudflare Worker (keeps your Anthropic API key
1718
server-side) and a widget embed.
1819

20+
### Fastest: scaffold a project
21+
22+
```bash
23+
npm create claudius@latest
24+
```
25+
26+
Answer a few prompts (framework — vanilla, React, or Next.js — theme, accent color,
27+
worker API URL, and optionally a Cloudflare Worker) and you get a ready-to-run
28+
project. See the
29+
[scaffolding guide](https://claudius-docs.pages.dev/getting-started/scaffolding/).
30+
31+
Prefer to wire things up by hand? Continue below.
32+
1933
### 1. Deploy the worker
2034

2135
```bash

‎create-claudius/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 PMDevSolutions
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎create-claudius/README.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# create-claudius
2+
3+
[![npm](https://img.shields.io/npm/v/create-claudius.svg)](https://www.npmjs.com/package/create-claudius)
4+
5+
Scaffold a [Claudius](https://claudius-docs.pages.dev) AI chat widget project in
6+
one command.
7+
8+
```bash
9+
npm create claudius@latest
10+
# or
11+
pnpm create claudius
12+
# or
13+
yarn create claudius
14+
```
15+
16+
You'll be prompted for:
17+
18+
- **Project name** — the new directory / package name
19+
- **Framework** — `vanilla` (CDN script embed), `react` (Vite), or `next` (Next.js App Router)
20+
- **Theme** — `auto` / `light` / `dark`, or a built-in theme (`default`, `minimal`, `playful`, `corporate`)
21+
- **Accent color** — a hex color for the widget
22+
- **API URL** — your deployed Claudius worker endpoint
23+
- Optionally, a **Cloudflare Worker** scaffold (`wrangler.toml` + KV stub + deploy runbook)
24+
25+
The generated project runs out of the box:
26+
27+
```bash
28+
cd my-app
29+
pnpm install
30+
pnpm dev
31+
```
32+
33+
## Non-interactive
34+
35+
Pass flags to skip the prompts (handy for CI):
36+
37+
```bash
38+
npm create claudius@latest my-app -- \
39+
--template react \
40+
--theme auto \
41+
--accent "#4f46e5" \
42+
--api-url https://my-worker.workers.dev \
43+
--worker \
44+
--yes
45+
```
46+
47+
| Flag | Values | Description |
48+
| --- | --- | --- |
49+
| `--template` | `vanilla` \| `react` \| `next` | Framework template |
50+
| `--theme` | `auto` \| `light` \| `dark` \| `default` \| `minimal` \| `playful` \| `corporate` | Widget theme |
51+
| `--accent` | `#rrggbb` | Accent color |
52+
| `--api-url` | URL | Worker chat endpoint |
53+
| `--worker` | — | Also scaffold a Cloudflare Worker |
54+
| `--pm` | `npm` \| `pnpm` \| `yarn` \| `bun` | Package manager shown in next steps |
55+
| `--yes`, `-y` | — | Accept defaults for any unspecified prompt |
56+
57+
## What you get
58+
59+
- **vanilla** — a static Vite site that loads the widget from the jsDelivr CDN via a
60+
single `<script>` tag and `window.ClaudiusConfig`.
61+
- **react** — a Vite + React + TypeScript app using the `claudius-chat-widget`
62+
component and its stylesheet.
63+
- **next** — a Next.js (App Router) + TypeScript app with a client-side widget wrapper.
64+
65+
See the [documentation](https://claudius-docs.pages.dev) for worker setup and
66+
configuration.
67+
68+
MIT © PMDevSolutions

‎create-claudius/package.json‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
{
2+
"name": "create-claudius",
3+
"version": "1.6.0",
4+
"description": "Scaffold a Claudius AI chat widget project in one command.",
5+
"keywords": [
6+
"claudius",
7+
"create",
8+
"create-claudius",
9+
"scaffold",
10+
"cli",
11+
"chat-widget",
12+
"claude",
13+
"ai-chat"
14+
],
15+
"author": "PAMulligan",
16+
"license": "MIT",
17+
"homepage": "https://claudius-docs.pages.dev",
18+
"repository": {
19+
"type": "git",
20+
"url": "git+https://github.com/PMDevSolutions/Claudius.git",
21+
"directory": "create-claudius"
22+
},
23+
"bugs": {
24+
"url": "https://github.com/PMDevSolutions/Claudius/issues"
25+
},
26+
"type": "module",
27+
"bin": {
28+
"create-claudius": "dist/index.js"
29+
},
30+
"files": [
31+
"dist",
32+
"templates"
33+
],
34+
"engines": {
35+
"node": ">=18"
36+
},
37+
"publishConfig": {
38+
"access": "public"
39+
},
40+
"scripts": {
41+
"build": "tsup",
42+
"dev": "tsup --watch",
43+
"typecheck": "tsc --noEmit",
44+
"test": "vitest run",
45+
"test:watch": "vitest"
46+
},
47+
"dependencies": {
48+
"@clack/prompts": "^0.7.0",
49+
"picocolors": "^1.1.0"
50+
},
51+
"devDependencies": {
52+
"@types/node": "^22.0.0",
53+
"tsup": "^8.3.0",
54+
"typescript": "^5.8.0",
55+
"vitest": "^4.1.0"
56+
}
57+
}

0 commit comments

Comments
 (0)