01 — Project Setup

Goal: Bootstrap an empty Webda project with the right dependencies, TypeScript config, and a minimal webda.config.json so that webdac build succeeds.

Files touched: package.json, tsconfig.json, webda.config.json, src/index.ts.

Concepts: project layout, webda.module.json (auto-generated by webdac build), $schema for IDE autocomplete.

Walkthrough

1. Create the project directory

mkdir my-blog
cd my-blog

2. Initialize pnpm

pnpm init

Accept all defaults. You'll end up with a bare package.json.

3. Set the package type and namespace

Edit package.json so it reads:

package.json

{
  "name": "my-blog",
  "version": "1.0.0",
  "description": "Blog API built with Webda",
  "type": "module",
  "main": "lib/index.js",
  "scripts": {
    "build": "webdac build",
    "debug": "webda debug"
  },
  "engines": {
    "node": ">=22.0.0"
  },
  "webda": {
    "namespace": "MyBlog"
  }
}

The "type": "module" field is required — Webda is fully ESM. The "webda.namespace" field prefixes every model and service you export so they live under MyBlog/ in configuration.

4. Install Webda dependencies

pnpm add @webda/core @webda/models @webda/utils
pnpm add -D @webda/compiler typescript @types/node

Package	Role
@webda/core	Application runtime, HTTP server, Bean/Operation decorators
@webda/models	UuidModel, Model, relation types (BelongTo, OneToMany, …)
@webda/utils	Utility helpers (dirty-tracking, etc.)
@webda/compiler	webdac CLI — compiles TypeScript and generates webda.module.json

5. Create tsconfig.json

tsconfig.json

{
  "compilerOptions": {
    "target": "es2020",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "outDir": "./lib",
    "rootDir": "./src",
    "strict": false,
    "sourceMap": true,
    "declaration": true,
    "experimentalDecorators": false,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "declarationMap": true
  },
  "include": ["src/**/*", ".webda/module.d.ts"],
  "exclude": ["**/node_modules", "**/*.spec.ts"]
}

Key points:

• experimentalDecorators: false — Webda uses the TC39 stage-3 decorator proposal, not the legacy flag.
• module: nodenext — TypeScript 7 removed the legacy resolvers, and relative imports carry their .js extension (./user.model.js).
• No compiler plugin is needed: webdac build generates accessors and relations itself.
• .webda/module.d.ts is generated by webdac build so your models' types are available project-wide.

6. Create a minimal webda.config.json

webda.config.json

{
  "$schema": ".webda/config.schema.json",
  "parameters": {
    "website": "http://localhost:18080"
  },
  "services": {
    "HttpServer": {
      "type": "Webda/HttpServer",
      "autoTls": true
    },
    "DomainService": {
      "type": "Webda/DomainService"
    },
    "RESTService": {
      "type": "Webda/RESTOperationsTransport"
    }
  }
}

• HttpServer — starts the HTTPS server on port 18080. autoTls: true generates a self-signed certificate on first run so curl -k works immediately.
• DomainService — discovers all models and wires up their REST routes automatically.
• RESTService — exposes @Operation-decorated methods over HTTP.

7. Create the entry-point stub

mkdir src
touch src/index.ts

src/index.ts stays empty for now — the compiler picks up all .ts files in src/. You'll add model exports in later steps.

8. Build

pnpm exec webdac build

This compiles TypeScript to lib/ and writes two generated artefacts:

Artefact	Description
webda.module.json	Lists every model/service the compiler found — loaded at runtime
.webda/config.schema.json	JSON Schema for webda.config.json — powers IDE autocomplete

Generated files

Never edit webda.module.json or anything inside .webda/ by hand. They are regenerated on every webdac build.

Verify

pnpm exec webdac build

Compiling...
Done

After the build, confirm the artefacts exist:

ls webda.module.json .webda/config.schema.json

webda.module.json   .webda/config.schema.json

What's next

→ 02 — User Model