tw-framework 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TW Framework Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# TW Framework
+
+Full-stack web framework for building sites and apps with `.tw` pages, `.twm` server modules and `.tss` styles — compiled by the TW Compiler, hydrated by TW VDOM 1, served anywhere.
+
+## Install
+
+```bash
+bun add -d tw-framework
+```
+
+The CLI runs on Node 18+ for `tw create`, `tw build`, `tw test` and `tw adapter`. `tw dev` and `tw serve` use the Bun runtime.
+
+## Quickstart
+
+```bash
+# scaffold an app
+npx create-tw-framework@latest my-site
+cd my-site
+
+# develop (http://localhost:3000)
+bunx tw-framework dev
+
+# production build -> .tw/
+bunx tw-framework build
+
+# production server (Bun)
+bunx tw-framework serve
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `tw create <name>` | Scaffold a new app (pages, API routes, layout, config) |
+| `tw dev` | Dev server with on-demand compilation |
+| `tw build` | Production build to `.tw/` (pages, client chunks, route-split CSS) |
+| `tw serve` | Production server (Bun) — pages, `.twm` APIs, middleware |
+| `tw test` | Run the app test suite (Bun and Node) |
+| `tw check` | Diagnostics for the current project |
+| `tw ship` | Generate deployment configs (Vercel, Netlify, Cloudflare, Docker) |
+| `tw adapter <name>` | Deployment adapters: `node`, `bun`, `docker`, `vercel` |
+| `tw plugin` | Manage project plugins |
+
+## Deployment adapters
+
+```bash
+# zero-dependency Node server for the build output (static sites)
+bunx tw-framework adapter node && node server.mjs
+
+# full server (pages + APIs) on Bun
+bunx tw-framework adapter bun && bun server.ts
+
+# Docker (full + static Dockerfiles, compose file)
+bunx tw-framework adapter docker
+
+# Vercel
+bunx tw-framework adapter vercel
+```
+
+## Learn more
+
+- [Full documentation](https://github.com/tw-origin/tw-framework/blob/main/docs/framework-overview.md) — 183 guides and references
+- [Setup guide](https://github.com/tw-origin/tw-framework/blob/main/docs/setup-guide.md) — templates, editors, first app
+- [Deployment guides](https://github.com/tw-origin/tw-framework/blob/main/docs/guide-vercel.md) — Vercel, Netlify, Docker, AWS and more
+- [Repository](https://github.com/tw-origin/tw-framework)
+
+MIT licensed.

package/dist/adapters/aws/README.md

@@ -0,0 +1,37 @@
+# Deploying TW Framework to AWS
+
+Generated by `tw adapter aws`. Two paths, depending on what you built:
+
+## A. Static output → S3 + CloudFront
+
+For static and pre-rendered output (no `.twm` APIs served per request):
+
+1. Create an S3 bucket (block public access off for static hosting, or keep it
+   private and front it with CloudFront — recommended).
+2. Create a CloudFront distribution with the bucket as origin, default root
+   object `index.html`.
+3. Deploy:
+
+```bash
+tw build
+BUCKET=my-bucket DISTRIBUTION_ID=E123ABC bash deploy-s3.sh
+```
+
+`deploy-s3.sh` uploads `/assets/*` and `/js/*` with immutable cache headers
+and everything else with `no-cache`, then invalidates CloudFront.
+
+## B. Full server (pages + APIs + middleware) → containers
+
+The full TW server runs in a container. Use the Docker adapter and deploy to
+any container service:
+
+```bash
+tw adapter docker
+```
+
+- **App Runner**: point a service at the repo (or ECR image) — `PORT` is
+  injected and honoured.
+- **ECS / Fargate**: use the same image; the task port maps to `PORT`.
+- **Lightsail containers**: same image, same port handling.
+
+The image listens on `PORT` (default 8000) and serves the complete app.

package/dist/adapters/aws/deploy-s3.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Deploy the .tw/ build output to AWS S3 + CloudFront.
+# Generated by `tw adapter aws`.
+#
+# Usage:
+#   tw build
+#   BUCKET=my-bucket DISTRIBUTION_ID=E123ABC bash deploy-s3.sh
+#
+# Requires the AWS CLI configured with permissions for the bucket
+# (and the distribution, when DISTRIBUTION_ID is set).
+set -euo pipefail
+
+BUCKET="${BUCKET:?set BUCKET=<your-bucket>}"
+DISTRIBUTION_ID="${DISTRIBUTION_ID:-}"
+
+if [ ! -d .tw ]; then
+  echo "Run 'tw build' first — .tw/ not found."
+  exit 1
+fi
+
+# Hashed assets never change — cache them forever.
+aws s3 sync .tw/assets "s3://$BUCKET/assets" \
+  --cache-control "public, max-age=31536000, immutable" --delete
+
+aws s3 sync .tw/js "s3://$BUCKET/js" \
+  --cache-control "public, max-age=31536000, immutable" --delete
+
+# HTML revalidates on every request.
+aws s3 sync .tw "s3://$BUCKET" \
+  --exclude "assets/*" --exclude "js/*" \
+  --cache-control "no-cache" --delete
+
+# Invalidate CloudFront so new HTML is live immediately.
+if [ -n "$DISTRIBUTION_ID" ]; then
+  aws cloudfront create-invalidation \
+    --distribution-id "$DISTRIBUTION_ID" --paths "/*"
+fi
+
+echo "Deployed to s3://$BUCKET"

package/dist/adapters/bun/server.ts

@@ -0,0 +1,30 @@
+/**
+ * TW Framework — Bun deployment adapter (full server).
+ *
+ * Runs the production TWServer (pages + .twm APIs + middleware + config)
+ * on Bun's native HTTP server. Copy this file next to your app (or generate
+ * it with `tw adapter bun`) and run:
+ *
+ *   bun server.ts
+ *
+ * Env: PORT (default 3000) HOST (default 0.0.0.0) TW_ROOT (default .tw)
+ */
+
+import { TWServer } from "@tw/server";
+import { join } from "node:path";
+
+const rootDir = process.cwd();
+const port = Number(process.env.PORT ?? 3000);
+const host = process.env.HOST ?? "0.0.0.0";
+const staticDir = process.env.TW_ROOT ?? join(rootDir, ".tw");
+
+const server = new TWServer({
+  rootDir,
+  port,
+  host,
+  staticDir,
+} as any);
+
+try { server.loadRoutes(); } catch { /* optional */ }
+try { server.loadMiddleware(); } catch { /* optional */ }
+await server.start();

package/dist/adapters/caddy/Caddyfile

@@ -0,0 +1,25 @@
+# Caddyfile for TW Framework
+# Generated by `tw adapter caddy`.
+#
+# Replace example.com with your domain. Caddy issues and renews HTTPS
+# certificates automatically.
+#
+# Static output only (pages + pre-rendered routes). For the full server,
+# run `tw serve` (or the node/bun adapter) and proxy to it instead:
+#
+#   example.com {
+#       reverse_proxy 127.0.0.1:8000
+#   }
+
+example.com {
+    root * .tw
+    encode gzip
+
+    # Hashed assets never change — cache them forever.
+    @immutable path /assets/* /js/*
+    header @immutable Cache-Control "public, max-age=31536000, immutable"
+
+    # Clean URLs: /about serves about/index.html
+    try_files {path} {path}/ /{path}.html
+    file_server
+}

package/dist/adapters/cloudflare/_headers

@@ -0,0 +1,12 @@
+# Cloudflare Pages headers
+# Hashed assets never change — cache them forever.
+/assets/*
+  Cache-Control: public, max-age=31536000, immutable
+
+/js/*
+  Cache-Control: public, max-age=31536000, immutable
+
+/*
+  X-Content-Type-Options: nosniff
+  X-Frame-Options: DENY
+  Referrer-Policy: strict-origin-when-cross-origin

package/dist/adapters/cloudflare/_redirects

@@ -0,0 +1,4 @@
+# Cloudflare Pages redirects — one per line:
+#   /old-path  /new-path  301
+#
+# Netlify-style syntax: source, destination, status code.

package/dist/adapters/cloudflare/wrangler.toml

@@ -0,0 +1,13 @@
+# Cloudflare Pages deployment for TW Framework
+# Generated by `tw adapter cloudflare`.
+#
+# Build configuration (also settable in the Cloudflare dashboard):
+#   Build command:      tw build
+#   Build output dir:   .tw
+#
+# Deploy with git integration (push to deploy) or:
+#   npx wrangler pages deploy .tw
+
+name = "tw-app"
+compatibility_date = "2024-11-01"
+pages_build_output_dir = ".tw"

package/dist/adapters/digitalocean/.do/app.yaml

@@ -0,0 +1,15 @@
+# DigitalOcean App Platform spec for TW Framework
+# Generated by `tw adapter digitalocean`.
+#
+# Connect the repo in the DigitalOcean control panel (Apps → Create App),
+# pick the repository and branch — this spec configures the service.
+#
+# Static output (pages + pre-rendered routes). For the full server
+# (.twm APIs + middleware), run `tw adapter docker` instead and change
+# the service below to a dockerfile build.
+
+name: tw-app
+static_sites:
+  - name: web
+    build_command: npm install && npx tw build
+    output_dir: .tw

package/dist/adapters/docker/.dockerignore

@@ -0,0 +1,7 @@
+node_modules
+.tw
+.git
+.env
+.env.*
+dist
+*.log

package/dist/adapters/docker/Dockerfile

@@ -0,0 +1,35 @@
+# TW Framework — production Docker image (full server: pages + .twm APIs).
+#
+#   docker build -t tw-app .
+#   docker run -p 8000:8000 tw-app
+#
+# Static site (no .twm API routes)? Use Dockerfile.static instead —
+# its runtime is a tiny zero-dependency Node alpine image.
+
+# ---- Stage 1: install + build ----
+FROM oven/bun:1 AS build
+WORKDIR /app
+
+# Install dependencies first (layer cache)
+COPY package.json bun.lock* ./
+RUN bun install
+
+# The TW CLI (published as tw-framework on npm)
+RUN bun add -d tw-framework
+
+# Build the app
+COPY . .
+RUN bunx tw build
+
+# ---- Stage 2: runtime ----
+FROM oven/bun:1
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV PORT=8000
+ENV HOST=0.0.0.0
+
+COPY --from=build /app ./
+
+EXPOSE 8000
+CMD ["bunx", "tw", "serve"]

package/dist/adapters/docker/Dockerfile.static

@@ -0,0 +1,27 @@
+# TW Framework — static-site Docker image (no .twm API routes).
+# Runtime is zero-dependency Node 20 alpine serving the compiled .tw/ output.
+
+# ---- Stage 1: build ----
+FROM oven/bun:1 AS build
+WORKDIR /app
+
+COPY package.json bun.lock* ./
+RUN bun install
+RUN bun add -d tw-framework
+
+COPY . .
+RUN bunx tw build
+
+# ---- Stage 2: run (tiny) ----
+FROM node:20-alpine
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV PORT=8000
+ENV HOST=0.0.0.0
+
+COPY --from=build /app/.tw ./.tw
+COPY server.mjs ./server.mjs
+
+EXPOSE 8000
+CMD ["node", "server.mjs"]

package/dist/adapters/docker/docker-compose.yml

@@ -0,0 +1,8 @@
+services:
+  web:
+    build: .
+    ports:
+      - "8000:8000"
+    environment:
+      - NODE_ENV=production
+    restart: unless-stopped

package/dist/adapters/firebase/firebase.json

@@ -0,0 +1,31 @@
+{
+  "hosting": {
+    "public": ".tw",
+    "ignore": [
+      "firebase.json",
+      "**/.*",
+      "**/node_modules/**"
+    ],
+    "cleanUrls": true,
+    "headers": [
+      {
+        "source": "/assets/**",
+        "headers": [
+          {
+            "key": "Cache-Control",
+            "value": "public, max-age=31536000, immutable"
+          }
+        ]
+      },
+      {
+        "source": "/js/**",
+        "headers": [
+          {
+            "key": "Cache-Control",
+            "value": "public, max-age=31536000, immutable"
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/adapters/fly/fly.toml

@@ -0,0 +1,32 @@
+# Fly.io deployment for TW Framework
+# Generated by `tw adapter fly`.
+#
+# 1. Run `tw adapter docker` first — fly deploys the container image.
+# 2. fly launch      (first time — picks a region, creates the app)
+# 3. fly deploy
+#
+# The container listens on PORT (default 8000), which matches
+# internal_port below. The full server (pages + .twm APIs + middleware)
+# runs on every machine.
+
+app = "tw-app"
+primary_region = "bom"
+
+[build]
+
+[http_service]
+  internal_port = 8000
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+  min_machines_running = 1
+
+  [http_service.concurrency]
+    type = "requests"
+    soft_limit = 200
+    hard_limit = 250
+
+  [[http_service.checks]]
+    interval = "10s"
+    timeout = "2s"
+    grace_period = "5s"

package/dist/adapters/github-pages/.github/workflows/deploy.yml

@@ -0,0 +1,41 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+
+      - run: bun install
+
+      - run: bunx tw build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: .tw
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

package/dist/adapters/github-pages/.nojekyll

@@ -0,0 +1 @@
+# GitHub Pages must not run Jekyll processing on the .tw/ output.