create-weftly
v0.2.0
Published
Scaffold a Weftly customer website (Next.js) with connection, agent skills and MCP config.
Maintainers
Readme
create-weftly
Legt eine neue Weftly-Kundenwebsite an: lädt das
Customer Template,
schreibt die Verbindung in .env.local, installiert die Agent-Skills
weftly-customer und weftly-mcp, trägt den Weftly-MCP-Server in .mcp.json
ein, installiert die Abhängigkeiten und legt ein Git-Repository an.
Voraussetzung: Node.js 20.17 oder neuer.
Aufruf
npm create weftly@latest kundenwebsite
# oder
npx create-weftly kundenwebsitepnpm create weftly und yarn create weftly funktionieren ebenso. Bei
npm create stehen Optionen hinter --:
npm create weftly@latest kundenwebsite -- --environment production --port 3002Interaktiv
Ohne Optionen fragt das Tool nacheinander:
- Vorschau – gehostet (Website wird deployt, Konfiguration aus Einstellungen → Verbindung) oder lokal (Entwicklungskopie, Einstellungen → Entwicklung).
- Verbindung – Mit Weftly anmelden (empfohlen): der Browser öffnet Weftly, du gibst den im Terminal angezeigten Code ein, wählst Workspace und Projekt (bei lokaler Vorschau optional die Entwicklungskopie) und bestätigst; ein neuer API-Schlüssel und die Konfiguration kommen automatisch ins Terminal. Bei Abbruch (Strg+C), Ablehnung oder Ablauf geht es mit dem Einfügen weiter. Alternativ: Konfigurationsblock einfügen (die Eingabe wird nicht angezeigt; Abschluss mit zweimal Enter), Werte einzeln eingeben (der API-Schlüssel wird verdeckt eingegeben) oder überspringen.
- Projekt-ID, falls sie noch fehlt.
- Umgebung –
staging(lokal und Vercel Preview) oderproduction. - Dev-Port – Standard
3001, wird insdev-Skript geschrieben. - Paketmanager – Standard ist der aufrufende (
npm create→ npm,pnpm create→ pnpm, …). .mcp.jsonschreiben? (Standard: ja)- Git-Repository initialisieren? (Standard: ja)
Ohne Rückfragen
Mit --yes oder ohne Terminal (stdin ist kein TTY) gelten die Standardwerte.
Die Verbindung liest du dann mit --env-file aus einer Datei oder von stdin:
npx create-weftly meine-website --yes --env-file weftly.env
pbpaste | npx create-weftly meine-website --yes --env-file -Ohne --env-file bleibt die Verbindung leer; trage sie später in .env.local
ein. Mit --login meldest du dich auch ohne weitere Rückfragen im Browser an
(schlägt die Anmeldung fehl, bricht das Tool ab):
npx create-weftly meine-website --yes --loginBrowser-Anmeldung (Device-Flow)
--login bzw. „Mit Weftly anmelden“ folgt dem OAuth Device Authorization
Grant (RFC 8628): Das CLI holt bei <api-url>/api/cli/device einen Code, öffnet
<api-url>/cli/device (sonst die Adresse manuell öffnen), du gibst dort den Code
aus dem Terminal ein, und das CLI fragt <api-url>/api/cli/device/token im vorgegebenen
Intervall ab. Nach deiner Freigabe liefert Weftly genau einmal Projekt-ID,
API-URL, Builder-Origins, CDN-Hostname und einen frisch erzeugten
Projekt-API-Schlüssel (Bezeichnung create-weftly <datum>, widerrufbar unter
Einstellungen → Verbindung). Der Code gilt 10 Minuten. Dein Konto braucht die
Rolle Editor oder Admin und Zugriff auf das Projekt. Ältere Weftly-Instanzen
ohne diese Endpunkte erkennt das CLI und bietet das Einfügen an.
Offline mit lokalem Template
Im Monorepo kannst du statt des GitHub-Downloads einen lokalen Ordner kopieren:
npx create-weftly ../test-website --template-dir apps/customer-template --no-installnode_modules, .next, .git, .env und .env*.local werden dabei nicht
mitkopiert.
Optionen
| Option | Bedeutung |
| --- | --- |
| -y, --yes | Keine Rückfragen, Standardwerte verwenden |
| --project-id <id> | Weftly-Projekt-ID (NEXT_PUBLIC_WEFTLY_PROJECT_ID) |
| --environment <env> | staging (Standard) oder production |
| --preview <modus> | hosted (Standard) oder local (Einstellungen → Entwicklung) |
| --port <port> | Dev-Port (Standard 3001) |
| --package-manager <pm> | npm, pnpm, yarn oder bun (Standard: aufrufender Paketmanager) |
| --login | Im Browser bei Weftly anmelden; Schlüssel und Konfiguration kommen automatisch |
| --env-file <pfad\|-> | Konfigurationsblock aus Datei lesen (- = stdin) |
| --api-url <url> | Weftly-/Content-API-Origin (Standard https://app.weftly.site) |
| --skip-connection | Verbindung überspringen (später in .env.local eintragen) |
| --template-ref <ref> | Branch/Tag des Templates (Standard main) |
| --template-dir <pfad> | Template aus lokalem Ordner kopieren (offline, z. B. apps/customer-template) |
| --no-git | Kein git init |
| --no-install | Abhängigkeiten nicht installieren |
| --no-mcp | Keine .mcp.json schreiben |
| --no-skills | Agent-Skills nicht kopieren |
| -h, --help | Hilfe anzeigen |
| -v, --version | Version anzeigen |
--project-id und --api-url ergänzen oder überschreiben die Werte aus dem
Konfigurationsblock. Widerspricht --project-id der Projekt-ID im Block, bricht
das Tool ab.
Das Template wird als Tarball von codeload.github.com geladen, ohne
Git-Historie. Für ein privates Template setzt du GITHUB_TOKEN (oder
GH_TOKEN); der Download läuft dann über api.github.com. Ohne Token und bei
HTTP 404 nutzt das Tool automatisch eine vorhandene Anmeldung der GitHub CLI
(gh auth login).
Was erzeugt wird
Template-Dateien im Zielordner. Der Ordner muss neu oder leer sein (
.git,.DS_Store,.idea,.vscode,.gitkeepsind erlaubt). Schlägt ein Schritt fehl, räumt das Tool den Ordner wieder auf..env.localaus.env.example, mit Dateirechten600. Vorhandene Zuweisungen werden an Ort und Stelle gefüllt, unbekannte Variablen am Ende ergänzt.package.json:nameaus dem Ordnernamen,--port <port>imdev-Skript. Bei pnpm, yarn oder bun werdenpackage-lock.jsonund das FeldpackageManagerentfernt.Agent-Skills
weftly-customerundweftly-mcpin.claude/skills/und.agents/skills/(Claude Code bzw. Codex und andere Agenten)..mcp.jsonmit dem Serverweftly; andere Einträge einer vorhandenen Datei bleiben erhalten:{ "mcpServers": { "weftly": { "type": "http", "url": "https://app.weftly.site/api/mcp" } } }Die URL folgt
WEFTLY_CONTENT_API_URL(<origin>/api/mcp).Abhängigkeiten (außer mit
--no-install) und ein Git-Repository mit erstem Commit. Liegt der Ordner schon in einem Repository, wird Git übersprungen.
Prüfregeln für die Verbindung
Fehlermeldungen nennen nur Variablennamen, nie Werte.
WEFTLY_CONTENT_API_KEYmuss mitwfk_beginnen und darf keine Leerzeichen enthalten. Der Platzhalter aus dem Builder (wfk_PASTE_A_MINTED_KEY_HERE) zählt als fehlender Schlüssel; du bekommst eine Warnung.- Geheime Werte dürfen nie mit
NEXT_PUBLIC_beginnen (z. B.NEXT_PUBLIC_WEFTLY_CONTENT_API_KEY) – sie landeten sonst im Browser-Bundle. WEFTLY_CONTENT_API_URLund jeder Eintrag inWEFTLY_BUILDER_ORIGINS(kommagetrennt) müssen Origins ohne Pfad, Suchparameter und Zugangsdaten sein, mithttps://.http://ist nur fürlocalhost,127.0.0.1und[::1]erlaubt.NEXT_PUBLIC_WEFTLY_PROJECT_ID: Buchstaben, Ziffern,-oder_, 6–64 Zeichen, beginnt mit Buchstabe oder Ziffer.WEFTLY_ENVIRONMENT:stagingoderproduction.NEXT_PUBLIC_BUNNY_PULLZONE_HOSTNAME: Hostname ohnehttps://und ohne Pfad.NEXT_PUBLIC_WEFTLY_DEFAULT_LOCALE: Sprachcode wiedeoderen-US.- Unbekannte Variablen werden mit Warnung unverändert übernommen.
Sicherheit
- Der API-Schlüssel wird weder angezeigt noch protokolliert; die Zusammenfassung meldet nur „gesetzt“ oder „fehlt“.
.env.localist im Template per.gitignorevon Git ausgeschlossen und nur für dich lesbar (600). Hinterlege dieselben Werte separat beim Hosting..mcp.jsonenthält keine Zugangsdaten. Claude Code meldet sich per OAuth an, wenn du im Projekt/mcpausführst.- Browser-Anmeldung: Der Gerätecode wird nie angezeigt, Weftly speichert ihn
nur gehasht. Freigaben gelten einmalig; der Schlüssel wird erst beim Abholen
erzeugt und nur einmal ausgeliefert. Den Code tippst du selbst ab – Weftly
übernimmt ihn nie aus einem Link; gib nur frei, wenn du create-weftly gerade
selbst gestartet hast. Das CLI öffnet ausschließlich
<api-url>/cli/deviceund entfernt Steuerzeichen aus Serverangaben vor der Ausgabe.
Nächste Schritte
Am Ende gibt das Tool die passenden Schritte aus, etwa:
cd kundenwebsite(und ggf.npm install)- Fehlende Verbindung in
.env.localergänzen npm run dev→http://localhost:3001http://localhost:3001/preview/deöffnen – die Vorschau-Route für den Builder zeigt ohne Builder den Verbindungsstatus.- Lokal: unter Einstellungen → Entwicklung die Adresse
http://localhost:3001eintragen. Gehostet: Website deployen, Variablen beim Hosting hinterlegen und die Vorschau-URL in Weftly eintragen. - In Weftly unter Einstellungen → Verbindung den Status aktualisieren.
- Claude Code im Projekt starten und
/mcpausführen.
Ohne .mcp.json verbindest du Claude Code so:
claude mcp add --transport http weftly https://app.weftly.site/api/mcpEntwicklung
pnpm --filter create-weftly build # prüft zuerst die Skill-Kopien, dann tsc
pnpm --filter create-weftly typecheck
pnpm exec vitest run packages/create-weftly
node packages/create-weftly/dist/cli.js --helpDie Skills unter packages/create-weftly/skills/ sind Kopien aus skills/
(ohne das monorepo-interne GAPS.md). Nach Änderungen an einem Skill
pnpm skills:sync ausführen; pnpm check:skills (und der Build) schlägt bei
Abweichungen fehl. Die Liste der mitgelieferten Skills steht in
src/skills.ts (BUNDLED_SKILLS) und in scripts/sync-skills.mjs
(PACKAGE_SKILLS) – beide gleich halten.
Veröffentlichen
Wie die anderen Pakete manuell: Version in package.json erhöhen, dann
pnpm --filter create-weftly publish --access publicprepack führt den Build aus, der zuerst sync-skills --check aufruft. Ein
veröffentlichter Stand lässt sich nicht erneut veröffentlichen.
Lizenz
Weftly Community License – siehe LICENSE.
