Alchemy: Infrastructure as TypeScript

14.1A rés, amit betölt

Idézzük fel a 12. modul tanulságát: a wrangler.jsonc már ma is IaC — verziózza a bindingokat, route-okat, cronokat, limiteket. De van egy lyuk a képben, amit a 8. modulban is kimondtunk:

Ez a lyuk kicsinek tűnik, amíg egy stagingod és egy prodod van. Amint N környezet kellene (PR-onként egy, tenantonként egy, demó-példány egy ügyfélnek), a kézi lépések ismételgetése lesz a szűk keresztmetszet. Az Alchemy pontosan ezt a rést zárja be — de nem YAML-lel vagy HCL-lel, hanem TypeScripttel.

14.2Mi ez, és mi a modellje?

Az Alchemy egy TypeScript-natív IaC könyvtár: az erőforrás nem egy deklaratív blokk egy külön nyelvben, hanem egy async függvény, amit await-elsz. Nincs mögötte provider-processz, nincs külön futtatókörnyezet — sima JavaScript fut, ott, ahol te futtatod.

import alchemy from "alchemy";
import { Worker, D1Database, R2Bucket, KVNamespace } from "alchemy/cloudflare";

const app = await alchemy("my-saas");       // ① app — a projekt gyökere

const db = await D1Database("app-db");       // ② resource — létrehozza VAGY frissíti
console.log(db.id);                          // ③ az eredmény azonnal használható

await app.finalize();                        // ④ egyeztet + takarítja az árvákat

A modell öt fogalomból áll:

14.3Konkrét példa 1 — a teljes SaaS-infra egy fájlban

Így nézne ki a te stacked (12. modul konfigjának megfelelője, de kódként), stage-ekkel:

import alchemy from "alchemy";
import { Worker, D1Database, R2Bucket, KVNamespace } from "alchemy/cloudflare";

const app = await alchemy("my-saas");
const stage = app.stage;                    // "dev" | "staging" | "prod" | "pr-123"…
const isProd = stage === "prod";

// ---- erőforrások: a NÉV tartalmazza a stage-et, így nem ütköznek ----
const db = await D1Database("db", {
  name: `app-${stage}`,
  primaryLocationHint: isProd ? "weur" : undefined,   // 5b. modul
  migrationsDir: "./migrations",                        // deploykor alkalmazza
});

const uploads = await R2Bucket("uploads", { name: `uploads-${stage}` });
const config  = await KVNamespace("config",  { title: `config-${stage}` });

// ---- a Worker: a bindingokba a FENTI OBJEKTUMOKAT adod át ----
export const api = await Worker("api", {
  name: `my-saas-${stage}`,
  entrypoint: "./.output/server/index.mjs",      // Nuxt build kimenete (13. modul)
  compatibilityFlags: ["nodejs_compat"],
  assets: "./.output/public",

  bindings: {
    DB: db,                                      // nincs ID-copy-paste!
    UPLOADS: uploads,
    CONFIG: config,
    APP_ENV: stage,                              // sima var
    STRIPE_KEY: alchemy.secret.env.STRIPE_KEY,   // titkosítva az állapotban
  },

  routes: isProd
    ? ["app.example.com/*"]
    : [`${stage}.example.com/*`],              // stage-enként saját domain

  crons: isProd ? ["0 1 * * *"] : [],             // cron csak élesben!
  observability: { enabled: true,
                   headSamplingRate: isProd ? 0.1 : 1 },
});

console.log(`✅ ${stage}: ${api.url}`);
await app.finalize();

npx alchemy deploy --stage staging
npx alchemy deploy --stage prod
npx alchemy destroy --stage pr-123

Vesd össze a 12. modul konfigjával, ahol a staging és a production blokk szó szerint duplikálva volt (mert a bindingok nem öröklődnek). Itt ugyanazt a leírást paraméterezed — a duplikáció eltűnik, és a különbségek (isProd) egy helyen, olvashatóan látszanak.

14.4Mit ad ez a wrangler mellé? — hat konkrét dolog

1. Az erőforrás-létrehozás is kód lesz

Nincs több „futtasd le ezt a hat parancsot, aztán másold be az ID-ket". Az új fejlesztő egyetlen alchemy deploy --stage dev-vel felhúzza a saját teljes környezetét. Az ID-k sosem kerülnek kézzel a konfigba: a DB: db binding maga az objektum.

2. Ephemeral környezet PR-onként — a 8. modul fájó pontja

Emlékszel, mit kellett kimondani a 8. modulban? Hogy a PR-preview kód-preview, nem környezet-preview, és valódi per-PR izolációt a platform nem ad készen. Az Alchemy stage-modelljével ez néhány sor CI:

jobs:
  preview:
    steps:
      - run: npm ci && npm run build
      - run: npx alchemy deploy --stage pr-${{ github.event.number }}
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CF_TOKEN }}
          ALCHEMY_PASSWORD: ${{ secrets.ALCHEMY_PASSWORD }}
      # → saját Worker + saját D1 + saját bucket + saját URL, migrációkkal együtt

  cleanup:                      # PR zárásakor fut
    if: github.event.action == 'closed'
    steps:
      - run: npx alchemy destroy --stage pr-${{ github.event.number }}

Ez az a képesség, amiért önmagában érdemes megfontolni: minden PR kap egy teljesen izolált, valódi környezetet friss sémával — és a bezárásakor nyomtalanul eltűnik. Wranglerrel ezt magadnak kellene összeszkriptelned (a 8. modulban a „szkriptelt per-PR erőforrás" opció ~egy napnyi CI-munkára becsültem).

3. A típusok a forrásból jönnek, nem generált fájlból

A 11. modulban a wrangler types generált egy Env típust, amit szinkronban kellett tartani. Itt a Worker-objektum maga hordozza a típust:

// src/index.ts
import type { api } from "../alchemy.run";
type Env = typeof api.Env;      // a bindingok típusa a definícióból származik

Ha kiveszel egy bindinget a alchemy.run.ts-ből, a kódod azonnal fordítási hibát ad — nem kell külön generálási lépésre emlékezni.

4. Programozhatóság: ciklusok és feltételek az infrában

Ez a te per-tenant irányodban (5b. modul) különösen érdekes. Egy statikus konfigban nem tudsz „minden enterprise tenantnak külön adatbázist" leírni — kódban triviális:

const ENTERPRISE = [
  { slug: "acme",   region: "weur" },
  { slug: "globex", region: "oc"   },
  { slug: "initech", region: "enam" },
];

const tenantDbs = Object.fromEntries(
  await Promise.all(ENTERPRISE.map(async (t) => [
    `DB_${t.slug.toUpperCase()}`,
    await D1Database(`db-${t.slug}`, {
      name: `tenant-${t.slug}-${stage}`,
      primaryLocationHint: t.region,      // mindenki a saját régiójában (5b.2)
      migrationsDir: "./migrations",       // a séma mindenhol egységes
    }),
  ]))
);

export const api = await Worker("api", {
  bindings: { DB: sharedDb, ...tenantDbs, UPLOADS: uploads },
  // …
});

5. Titkok kezelése és olvasható állapot

Az alchemy.secret.env.X-szel megjelölt értékek titkosítva kerülnek az állapotfájlba (ALCHEMY_PASSWORD-del), tehát az állapot verziózható vagy megosztható anélkül, hogy kulcsok szivárognának. Maga az állapot pedig sima, olvasható JSON — egy PR-ban látod, mi változik az infrában, ami a Terraform-plan élményének a lightweight megfelelője.

6. Takarítás: destroy és árva-kezelés

Ha kiveszel egy erőforrást a kódból, a finalize() észreveszi és eltakarítja. Ez az, ami kézi világban sosem történik meg: marad tíz elárvult KV-namespace és három „temp" bucket, amiről senki nem tudja, kell-e még.

14.5Konkrét példa 2 — több Worker egy monorepóban

A 11. modulban láttad, hogy nagyobb rendszer szétválik: fő app + háttér-Worker. Alchemyben a Workerek közti kapcsolat is csak egy binding:

// háttér-Worker: queue consumer, cron
const jobs = await Worker("jobs", {
  name: `jobs-${stage}`,
  entrypoint: "./workers/jobs/index.ts",
  bindings: { DB: db, UPLOADS: uploads },
  crons: ["*/15 * * * *"],
});

// fő app: service bindinggel hívja a háttér-Workert (11. modul)
export const api = await Worker("api", {
  name: `api-${stage}`,
  entrypoint: "./.output/server/index.mjs",
  assets: "./.output/public",
  bindings: { DB: db, UPLOADS: uploads, JOBS_SERVICE: jobs },
});

Nincs „melyik Workert deployoljam előbb, és hogy hivatkozzon rá a másik" tánc — a függőség a kódban látszik, a sorrendet az await-ek adják.

14.6Hogyan viszonyul a wranglerhez? Együtt vagy helyette?

Nem kell mindenről lemondanod. A gyakorlati felosztás:

14.7Kockázatok — az őszinte rész

• Fiatal, közösségi projekt, nem Cloudflare-termék. Nincs formális stabilitási garancia, az API változhat, és nincs mögötte SLA vagy support. Egy bevételtermelő rendszer alap-infrastruktúrájánál ez valós kockázat.
• Az állapotfájl felelőssége a tiéd. Ha elveszik vagy szétcsúszik (két ember párhuzamosan deployol, nincs lockolás), az Alchemy „nem látja" a meglévő erőforrásokat — ilyenkor jön az adopt és a kézi rendrakás. Csapatban tedd megosztott backendre (pl. R2) és a deployt futtasd CI-ból, ne laptopokról.
• Lefedettség. A fő Cloudflare-primitívek megvannak (Workers, D1, KV, R2, Durable Objects), de mindig ellenőrizd, hogy amit használsz (Queues, Hyperdrive, Workflows, Containers, WAF-szabályok) támogatott-e a verzióban, amit telepítesz — különben marad a hibrid: rész-Alchemy, rész-wrangler, ami a legrosszabb világ.
• Csapat-tanulási görbe. Egy új fejlesztőnek a wrangler-konfig önmagyarázó; egy 200 soros alchemy.run.ts ciklusokkal és feltételekkel már programot jelent, amit érteni kell.
• Nem old meg mindent. A séma-migrációk fegyelme (8. modul: expand–contract, gated prod), a release-stratégia és az observability ugyanúgy a te dolgod marad.

14.8Döntési útmutató

14.9Ellenőrizd magad