Skip to main content

Get Started

This guide assumes you are a developer using an AI agent or working directly in a repo and want to get a W7S app deployed quickly with a clean shape from day one.

What W7S expects​

At a high level, W7S deploys a repository archive and exposes:

  • backend/webhook routes through https://<org>.w7s.cloud/<repo>/...
  • static frontend assets for the same repo
  • repo-scoped SQLite databases
  • account/session routes under /_account
  • plugin runtime access from your handlers

The opinionated repo layout is:

my-app/
  backend/
    src/
      health.ts
      notes.ts
      db/
        schema.ts
      db-helpers.ts
  db/
    app/
      migrations/
        0001_init.sql
  frontend/
    dist/
      index.html
      app.js
  w7s.site.json
  w7s.json
  .github/workflows/

The fastest way to start​

Use this order:

  1. Create a minimal backend route.
  2. Add database migrations under db/<database>/migrations.
  3. Add a Drizzle schema and use createW7SDbClient.
  4. Add a static frontend under frontend/dist.
  5. Add a deploy workflow that zips the repo and posts it to /_deploy.

Minimal backend​

Create w7s.json at repo root:

[
  {
    "type": "webhook",
    "path": "/health",
    "method": "GET",
    "handler": "./backend/src/health.ts",
    "auth": "none"
  }
]

Create backend/src/health.ts:

export default async function handle() {
  return {
    status: 200,
    body: {
      ok: true,
      service: "my-app",
    },
  };
}

After deploy, the route is available at:

https://<org>.w7s.cloud/<repo>/health

Database shape​

W7S discovers migrations from:

db/<databaseName>/migrations/*.sql

For the default app database:

db/app/migrations/0001_init.sql

Deploy runs those migrations before finalizing the backend snapshot.

Frontend shape​

Static site files live under:

frontend/dist/*

The most common setup is a SPA, configured with w7s.site.json:

{
  "version": 1,
  "root": "frontend/dist",
  "mode": "spa",
  "fallback": "/index.html",
  "cleanUrls": false
}

Deploy workflow​

Your GitHub Action typically:

  1. checks out the repo
  2. builds backend and/or frontend
  3. zips the repo
  4. posts the archive to:
https://<org>.w7s.cloud/<repo>/_deploy?artifact=source

W7S also supports scope=backend and scope=frontend if you want separate workflows for faster deploys.