Docs

@Component.define()
class Counter extends Component("x-counter") {
  @Component.prop() count = 0;
  @Component.event() inc() { this.count++; }
  render() {
    return html`<button @click=${this.inc}>${this.count}</button>`;
  }
}

import { Component, html, css } from "@youneed/dom";

@Component.define()
class Counter extends Component("x-counter") {
  static styles = css`button { font: inherit }`;

  @Component.prop() count = 0;          // reactive: assigning re-renders
  @Component.prop({ attribute: true }) label = "count"; // reflects <x-counter label="…">

  @Component.event() inc() { this.count++; } // auto-bound for @click

  render() {
    return html`<button @click=${this.inc}>${this.label}: ${this.count}</button>`;
  }
}

import { createRouter } from "@youneed/dom-router";

const router = createRouter({
  outlet: document.getElementById("app")!,
  mode: "history",                 // "hash" (default) · "history" · "query"
  routes: [
    { path: "/",            component: HomePage },       // a component CLASS…
    { path: "/users/:id",   component: "user-page" },    // …or a tag string. params: { id }
    { path: "*",            component: "not-found" },     // catch-all
  ],
});

router.navigate("/users/42");      // updates the URL + mounts <user-page>
router.current?.params;            // { id: "42" }

import { installDevtools, mountDevtoolsPanel } from "@youneed/devtools";

installDevtools();        // capture per-component state/props/events/styles
mountDevtoolsPanel();     // floating, dockable, interactive panel (state persists)

import { toReact, fromReact } from "@youneed/dom-adapter-react";

// dom → React: a real React component with typed props
const ReactUserCard = toReact(UserCard);
function Profile({ user }) {
  return <ReactUserCard user={user} onSelect={(e) => console.log(e.detail)} />;
}

// React → dom: a custom-element class wrapping a React component
const ReactChart = fromReact(Chart);
html`<${ReactChart.tagName} .props=${{ data }}></${ReactChart.tagName}>`;

import { Component, html } from "@youneed/dom";
import { createI18n } from "@youneed/i18n";
import { i18nProvider } from "@youneed/dom-provider-i18n";

const appI18n = createI18n({
  resources: { en: { hello: "Hello {name}" }, de: { hello: "Hallo {name}" } },
  locale: "en",
});

class Greeting extends Component("x-greeting", { providers: [i18nProvider(appI18n)] }) {
  render() {
    return html`<div>${this.i18n("hello", { name: "Ada" })}</div>`;
    //                       ^ typed: autocompletes "hello" and checks params
  }
}
// setLocale("de") → every subscribed component re-renders

import { Component, html } from "@youneed/dom";
import { timersProvider } from "@youneed/dom-provider-timers";

class Clock extends Component("x-clock", { providers: [timersProvider()] }) {
  time = this.signal(new Date());

  onMount() {
    this.timers.setInterval(() => this.time.set(new Date()), 1_000);
    // no teardown code — cancelled on disconnect
  }

  render() {
    return html`<time>${this.time.get().toLocaleTimeString()}</time>`;
  }
}

// delay rejects AbortError on disconnect; postTask maps to scheduler.postTask.
// Everything cancellable is Disposable:
{
  using tick = this.timers.setInterval(render, 100);
} // ← cancelled at end of scope, even on throw

import { Application, Controller, t, HttpError } from "@youneed/server";

const Cat = t.object({ name: t.string(), age: t.number() });

class Cats extends Controller("/cats", { guards: [requireApiKey] }) {
  @Controller.get("/:name", { params: t.object({ name: t.string() }), response: { 200: Cat } })
  async byName(ctx: Context) {
    const cat = lookup(ctx.params.name);
    if (!cat) throw new HttpError(404, { error: "Not found" }); // throw any status
    return cat;                                                  // validated against 200: Cat
  }

  @Controller.guard(isAdmin)            // per-method guard (stacks with class guards)
  @Controller.post({ body: Cat, response: { 201: Cat } })
  async create(ctx: Context) {
    return this.Response.json(ctx.body, { status: 201 });        // ctx.body is typed + validated
  }
}

Application(Cats)
  .use(requestLogger(), cors())          // global middleware (onion model)
  .openapi({ title: "Cats", version: "1.0.0" })   // → GET /openapi.json
  .listen(3000, (ctx) => console.log(`:${ctx.port}`));

import { IsEmail, IsNotEmpty, MinLength, IsOptional, IsInt, Min, validate } from "@youneed/schema";

class CreateUserDTO {
  @IsEmail() email!: string;
  @IsNotEmpty() @MinLength(8) password!: string;
  @IsOptional() @IsInt() @Min(18) age?: number;
}

const errors = validate(CreateUserDTO, await req.json());
// [] when valid, else:
// [{ property: "email", value: "nope", constraints: { isEmail: "email must be an email" } }]

import { Table, Orm, getRepository } from "@youneed/orm-sql";

class UsersTable extends Table("users") {
  @Table.primaryGeneratedColumn() id!: number;

  @Table.field("string")
  @Table.index({ group: "user_action" })
  userId!: string;

  @Table.field("string", { unique: true }) email!: string;
  @Table.column({ type: "boolean", default: true }) isActive!: boolean;

  @Table.oneToMany(() => Photo, (p) => p.user) photos!: Photo[];
}

await Orm({
  type: "sqlite",
  database: ":memory:",
  tables: [UsersTable, Photo],
  synchronize: true,
});

const users = getRepository(UsersTable);
const ada = await users.insert({ userId: "u1", email: "ada@x.com" });
await users.findOne({ email: "ada@x.com" }); // → UsersTable instance

import { Application } from "@youneed/server";
import { rateLimit, TokenBucket, KvFixedWindow } from "@youneed/server-middleware-rate-limit";
import { RedisKV } from "@youneed/kv-redis";

Application()
  .use(rateLimit({ windowMs: 60_000, max: 100 }))   // fixed window, global
  .use("/api", rateLimit({ strategy: new TokenBucket({ capacity: 50, refillPerSec: 5 }) }))
  // one shared limit across N instances — the counter lives in Redis
  .use("/auth", rateLimit({ strategy: new KvFixedWindow(new RedisKV({ url: process.env.REDIS_URL }), { windowMs: 60_000, max: 20 }) }))
  .listen(3000, () => {});

import { Application } from "@youneed/server";
import { jobs } from "@youneed/server-plugin-jobs";

const cron = jobs({
  jobs: [{ name: "cleanup", schedule: "0 */6 * * *", handler: purge }],
});

app.plugin(cron).listen(3000, () => {}); // start() on listen, stop() on drain

// still mutable after registration
cron.scheduler.add({ name: "heartbeat", schedule: { every: 30_000 }, handler: ping });
cron.scheduler.trigger("cleanup");       // run one now, bypassing the schedule

import { Page, mountPages, enablePageDevtools } from "@youneed/ssr";
import { Application } from "@youneed/server";

class About extends Page("/about", { title: "About" }) {
  render() { return AboutApp; }                  // a component class, instance, or HTML string
}

class Home extends Page("/", {
  title: "Home",
  clientScript: () => import("./client.ts"),     // type-checked; resolved to a URL
  speculation: { prerender: [{ source: "list", urls: [About.url], eagerness: "moderate" }] },
}) {
  render() { return HomeApp; }
}

enablePageDevtools();                            // embed page+routes payload (dev)
mountPages(Application(), Home, About).listen(3010, …);

import { ssr } from "@youneed/server-plugin-ssr";
import { meta } from "@youneed/ssr-plugin-meta";

class Post extends Page("/blog/:slug", {
  title: "Hello world",
  meta: {
    description: "An introductory post.",
    og: { type: "article", image: "/og/hello.png" },
    twitter: { card: "summary_large_image" },
  },
}) { /* … */ }

app.plugin(ssr({
  origin: "https://example.com",
  pages: [Post],
  modules: [meta({ siteName: "Example", twitterSite: "@example" })],
}));

import { ssr } from "@youneed/server-plugin-ssr";
import { sitemap } from "@youneed/ssr-plugin-sitemap";

app.plugin(ssr({
  origin: "https://example.com",
  pages: [Home, About, Pricing],
  modules: [
    sitemap({
      exclude: ["/admin", /^\/internal/],
      entries: [{ url: "/blog/launch", lastmod: "2026-06-01", priority: 0.8 }],
      defaults: { changefreq: "weekly", priority: 0.5 },
    }),
  ],
}));

import { ssr } from "@youneed/server-plugin-ssr";
import { robots } from "@youneed/ssr-plugin-robots";

app.plugin(ssr({
  origin: "https://example.com",
  modules: [
    robots({
      policies: [
        { userAgent: "*", disallow: ["/admin", "/api"], allow: "/api/public" },
        { userAgent: ["GPTBot", "CCBot"], disallow: "/" },
      ],
      sitemap: true, // → Sitemap: https://example.com/sitemap.xml
    }),
  ],
}));

import { Application, Command, Option, defaultOptions } from "@youneed/cli";

// A reusable, named option (its key + value type flow into `this.options`).
class FirstOption extends Option("--first", {
  short: "f",
  description: "display just the first substring",
}) {}

class SplitCommand extends Command({
  name: "split <string>", // grammar: a word + positional args
  description: "Split a string into substrings and display as an array",
  options: [FirstOption, { name: "-s, --separator <char>", default: "," }, ...defaultOptions()],
}) {
  execute(value: string) {
    // `value` is typed from `<string>`; `this.options` from the options tuple.
    const limit = this.options.first ? 1 : undefined;
    console.log(value.split(this.options.separator, limit));
  }
}

Application({
  name: "string-util",
  description: "CLI to some JavaScript string utilities",
  version: "0.0.8",
  commands: [SplitCommand],
  options: [...defaultOptions()],
});

import { Application, Command } from "@youneed/cli";
import { prompts } from "@youneed/cli-middleware-prompt";

class Setup extends Command("setup", { middleware: [prompts()] }) {
  async execute() {
    const name = await this.prompt.ask("Project name?", { default: "app" });
    const env = await this.prompt.choice("Environment", ["dev", "staging", "prod"]);
    const feats = await this.prompt.list("Features", ["ts", "lint", "tests"]);
    if (await this.prompt.confirm(`Create ${name}?`, { default: true })) {
      await this.prompt.spinner("scaffolding", () => scaffold(name, env, feats));
      await this.prompt.alert("Done!");
    }
  }
}

Application({ name: "create", commands: [Setup] }).run(["setup"]);

import { Application } from "@youneed/cli";
import { help } from "@youneed/cli-plugin-help";

Application({
  name: "ops",
  version: "1.0.0",
  description: "Operations toolkit",
  commands: [/* … */],
  plugins: [
    help({ examples: { split: ["ops split a,b,c --first"] } }),
  ],
}).run();

// ops help          → grouped command list with examples
// ops help split    → usage, options and examples for one command

import { Test, Fixture, TestApplication, expect } from "@youneed/test";

class Calculator {
  add(a: number, b: number) { return a + b; }
}

class CalcFixture extends Fixture<Calculator>({ name: "calc", scope: "test" }) {
  setup() { return new Calculator(); }
}

class CalcTest extends Test({ name: "Calculator" }) {
  @Test.use(CalcFixture) calc!: Calculator;

  @Test.it("adds two numbers")
  adds() {
    expect(this.calc.add(2, 3)).toBe(5);
  }
}

await TestApplication().addTests(CalcTest).run();

import { createLogger, format, ConsoleTransport } from "@youneed/logger";

const log = createLogger({
  level: "info",
  format: format.combine(format.timestamp(), format.redact(["ssn"]), format.json()),
  defaultMeta: { service: "api" },
  transports: [new ConsoleTransport()], // works in the browser and on the server
});

log.info("listening", { port: 3000 });
// {"level":"info","message":"listening","timestamp":"…","service":"api","port":3000}

const reqLog = log.child({ requestId: "r-42" }); // bindings on every record
reqLog.error("db down", { password: "hunter2" }); // password → "[REDACTED]"