Noweb

Noweb ist eine Next.js-App fuer Website-Templates, Projekte, Auth, Checkout und Deployment. Nutzer koennen Templates auswaehlen, Inhalte im Editor anpassen, Bilder hochladen und Projekte mit eigener Domain veroeffentlichen.

Schnellstart

npm install
npm run dev

Die App laeuft lokal unter http://localhost:3000.

Vor einem Pull Request oder Deploy:

npm run ci

Community-Templates

Die vollständige Anleitung für Erstellung, Assets, lokale Vorschau und automatische Veröffentlichung steht in templates/README.md.

Wichtige Befehle

• npm run dev startet Next lokal mit Webpack.
• npm run build baut die Produktionsversion.
• npm run start startet den gebauten Next-Server.
• npm run lint prueft den Code mit ESLint und erlaubt keine Warnings.
• npm run typecheck prueft TypeScript ohne Emit.
• npm run test fuehrt Unit-Tests aus.
• npm run test:e2e fuehrt den Playwright-Smoke gegen npm run start aus.
• npx @lnny/noweb create erstellt ein Community-Template; danach laufen die Befehle lokal ueber npx noweb.
• npm run ci fuehrt Audit, Typecheck, Lint, Tests, Build und E2E aus.

Struktur

• app/ enthaelt Seiten, Routen und Server Actions.
• app/page.tsx, app/HomeSections.tsx, app/Footer.tsx und app/menu.tsx bilden die Startseite und Navigation.
• app/docs/ enthaelt die oeffentliche Doku im Produkt.
• lib/auth/ konfiguriert Better Auth.
• lib/db.ts stellt die Postgres-Verbindung bereit.
• lib/object-storage.ts kapselt RustFS/R2-kompatiblen Object Storage.
• lib/env.ts validiert serverseitige Runtime-Konfiguration.
• lib/domain.ts normalisiert und validiert Domains.
• lib/templates/ enthaelt Template-Typen, Runtime-Helfer und lokale Templates.
• templates/index.ts ist generiert und soll nicht per Hand editiert werden.
• db.txt dokumentiert das aktuelle Datenbankschema.
• scripts/deploy-worker.mjs veroeffentlicht Projekte als statische Sites.
• .github/workflows/deploy.yaml deployed main per SSH auf den Server.

Umgebung

Mindestens benoetigt:

DATABASE_URL=postgresql://...
BETTER_AUTH_SECRET=...

Je nach Feature zusaetzlich:

RESEND_API_KEY=...
EMAIL_FROM=Noweb <[email protected]>

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

POLAR_ACCESS_TOKEN=...
POLAR_PRODUCT_ID=...
POLAR_SERVER=sandbox

RUSTFS_ACCESS_KEY=...
RUSTFS_SECRET_KEY=...
RUSTFS_BUCKET_NAME=...
RUSTFS_ENDPOINT=...
RUSTFS_PUBLIC_URL=...

SENTRY_DSN=...

Object Storage kann alternativ ueber die R2_* Variablen konfiguriert werden. Details stehen in docs/object-storage.md.

Wie die Hauptteile zusammenhaengen

Auth laeuft ueber Better Auth in lib/auth/server.ts. Die Daten liegen in Postgres, E-Mails werden ueber Resend verschickt, OAuth ist optional ueber Google und GitHub aktiv.

Projekte und Templates werden in Postgres gespeichert. Das aktuelle Schema steht in db.txt; Schema-Aenderungen werden direkt in Postgres ausgefuehrt und danach dort dokumentiert.

Checkout laeuft ueber Polar. Der kanonische Einstieg ist app/checkout/route.ts, nicht direkt der Better-Auth-Checkout. Details stehen in docs/checkout.md.

Bild-Uploads gehen ueber app/api/uploads/r2/route.ts in einen S3-kompatiblen Storage. Die oeffentliche URL kommt aus RUSTFS_PUBLIC_URL, R2_PUBLIC_URL oder PUBLIC_DEV_URL.

Template-Previews laufen in einer sandboxed iframe/srcDoc Runtime. Oeffentlich sichtbar werden Community-Templates nach erfolgreicher automatischer Validierung.

Der Deploy Worker nimmt unveroeffentlichte Projekte aus der Datenbank, liest die kompilierten Template-Dateien, validiert Domains und schreibt statische Sites nach SITES_DIR Standard: /etc/caddy/sites.

Deployment

Bei jedem Push auf main fuehrt GitHub Actions .github/workflows/deploy.yaml aus:

1. Per SSH auf den Server verbinden und origin/main auschecken.
2. npm ci ausfuehren.
3. Repository-Templates in die Datenbank und den Preview-Storage publizieren.
4. npm run build ausfuehren.
5. Den noweb-Service neu starten.

Die GitHub-Secrets muessen gesetzt sein:

• SERVER_HOST
• SERVER_USER
• SSH_PRIVATE_KEY

Auf dem Server muessen ausserdem Node, npm, die Runtime-Env-Variablen und der noweb systemd-Service vorhanden sein.

Aenderungs-Checkliste

Wenn du etwas aenderst, pruefe die abhaengigen Stellen mit:

• Startseite, Preise oder Marketingtext: app/page.tsx, app/HomeSections.tsx, app/Footer.tsx, app/menu.tsx, docs/checkout.md bei Preis-/Checkout-Aenderungen.
• Polar-Produkte oder Checkout: app/checkout/route.ts, lib/auth/server.ts, lib/polar.ts, docs/checkout.md, Env-Variablen auf Server/GitHub.
• Auth, Login, Verifizierung oder OAuth: lib/auth/server.ts, app/auth/**, Datenbanktabellen und Resend/OAuth-Env.
• Datenbank-Schema oder Query-Format: lib/db.ts, Server Actions in app/**/actions.ts, scripts/deploy-worker.mjs, db.txt.
• Template-Felder oder Customizations: Template-Definition, Editor-Komponenten in lib/editor/ und app/my-templates/[id]/, Deploy Worker, templates/index.ts nur ueber den Sync-Prozess aktualisieren.
• Template-Doku: passende Seite in app/docs/ aktualisieren und den Eintrag in app/docs/guides.ts pruefen.
• Bild-Uploads oder Storage: lib/object-storage.ts, app/api/uploads/r2/route.ts, docs/object-storage.md, Storage-Env auf dem Server.
• Projekt-Deployment oder Domains: scripts/deploy-worker.mjs, Caddy/systemd-Konfiguration, docs/deploy-worker.md.
• GitHub Deploy: .github/workflows/deploy.yaml, GitHub-Secrets, Serverpfad ~/noweb, systemd-Service noweb.
• Neue oder geaenderte Produktfunktion: vorhandene Doku aktualisieren oder eine kleine neue Seite in docs/ oder app/docs/ anlegen.

Launch-Blocker

• Echte Betreiberangaben in app/imprint/page.tsx, app/privacy/page.tsx und app/terms/page.tsx eintragen.
• Lokale und Server-Env pruefen. POLAR_SERVER darf nur sandbox oder production sein.
• Monitoring setzen: SENTRY_DSN oder dokumentierte Alternative.
• npm run ci muss vor Production gruen sein.

Wichtige Hinweise

• Dieses Projekt nutzt Next.js 16. Vor groesseren Next-Aenderungen die lokalen Docs in node_modules/next/dist/docs/ lesen.
• templates/index.ts ist generiert. Nicht manuell pflegen.
• JSON-Spalten muessen beim Schreiben mit JSON.stringify(...) gespeichert werden.
• Secrets gehoeren nicht ins Repository.
• Vor einem Deploy npm run ci ausfuehren.