DOCSEARCHbyAlgolia
Submit Docs

Alchemy Infrastructure-as-Effects

repository·main·Indexed 20 days ago

https://github.com/alchemy-run/alchemy

An 'Infrastructure-as-Effects' framework that unifies cloud infrastructure provisioning and application logic into a single, type-safe program using the Effect ecosystem. Alchemy eliminates YAML and glue code by treating cloud resources as first-class Effect components, supporting deployments for AWS (EKS, SageMaker HyperPod, S3/CloudFront) and Cloudflare.

Tokens
655.6K
Snippets
1.7K
Records
2.5K
Agent score
72%

What's inside Alchemy

  1. Overview of Cloudflare resources in Alchemy

    main

    Alchemy provides typed bindings for a wide range of Cloudflare services, categorized by their function in your application stack:

    Compute

    • Workers: The primary compute runtime for every app.
    • Durable Objects: Globally-unique stateful instances providing transactional storage and typed RPC.
    • Containers: Long-lived processes with arbitrary runtimes, paired with a Durable Object for typed RPC.
    • Workflows: Durable, multi-step jobs with checkpointed and replayable steps.

    Frontend

    • Vite: Deploy pure-Vite apps (SPAs, TanStack Start, React Router, SolidStart) as a Worker with assets.
    • Static sites: Any build command's static output.

    Data

    • D1: Serverless SQLite with migrations managed during deployment.
    • KV: Edge key-value storage for config, sessions, and lookups.
    • R2: Object storage with read/write-scoped bindings.
    • Hyperdrive: Edge connection pooling for external Postgres and MySQL.

    Messaging & Networking

    • Queues: At-least-once message delivery between Workers.
    • Domains & DNS: Management of zones, DNS records, and settings.
    • Email: Routing inbound mail and sending from Workers.

    Security

    • Secrets & env: Binding .env values and secrets directly into your Workers.

  2. What is Infrastructure-as-Effects?

    main

    Alchemy is an Infrastructure-as-Effects framework that treats cloud infrastructure and application logic as a single, type-safe Effect program.

    Key features include:

    • Unified Language: Resources, Lambdas/Workers, IAM, and SDKs are all defined in one Effect program without YAML or separate runtimes.
    • Bindings over Glue Code: A single call (e.g., S3.GetObject(bucket)) automatically wires the IAM policy, environment variables, and the typed SDK call.
    • Type-Safe Errors: Cloud API failures are represented as tagged Effect errors within the type system.
    • Multi-Cloud Support: Supports AWS (S3, SQS, DynamoDB, Kinesis, Lambda, EC2) and Cloudflare (Workers, R2, D1, Durable Objects).
    • Consistent Lifecycle: The same code and mental model are used for local development, deployment (plan/deploy), smoke testing, and CI.

  3. Overview of the Alchemy Design System

    main

    The Alchemy Design System is a visual and tonal framework for the alchemy brand. It is designed for a terminal-first, code-dense, dark-mode-only aesthetic. The system is used to build marketing pages (via Astro + Starlight), documentation, social posts, and slide decks that maintain a consistent identity.

    Core Brand Identity:

    • Visuals: Flat, quiet, near-black surfaces with a single signature accent color: mint green #00e599.
    • Signature Element: Hand-drawn sketch diagrams (arrows, circles, scribbled labels) used to explain abstract concepts.
    • Tone: Technical, calm, and opinionated, targeting senior TypeScript engineers. It avoids hype, emojis (in body copy), and exclamation marks.

  4. Compare AWS runtimes in Alchemy

    main

    Alchemy provides four primary runtimes for deploying Effect programs on AWS. Use the following comparison to decide which fits your workload:

    FeatureLambda (Default)ECSEKSEC2
    ModelPer-request, event-drivenAlways-on containersKubernetes objectsAlways-on machine
    CostPay per invocation; scales to zeroPay per running taskControl plane + Auto Mode nodesPay per running instance
    StartupCold starts (ms–s)Task launch (tens of seconds)Cluster (~10m), Pods (seconds)Instance boot (minutes)
    PackagingBundled zip (Rolldown)Docker image (auto-built/pushed)Docker image (auto-built/pushed)Bundled program on AMI
    NetworkingFunction URL (none required)VPC required (awsvpc)VPC required (LoadBalancer)Full VPC control

    Rule of Thumb:

    1. Start with Lambda. It has the lowest idle cost and the most complete documentation for bindings and event sources.
    2. Move to ECS if the workload is long-running (e.g., WebSockets) or exceeds the 15-minute Lambda limit.
    3. Pick EKS if you specifically need Kubernetes features like Helm charts, operators, or raw manifests.
    4. Use EC2 if you need low-level access to the OS, kernel, GPUs, or custom networking.

  5. What is Cloudflare Hyperdrive?

    main

    Cloudflare Hyperdrive is a managed connection pooler that sits between Cloudflare Workers and an external Postgres or MySQL database. It eliminates per-request TCP handshakes and connection storms by pooling connections at the edge.

    When using Hyperdrive, you should point it at the direct (non-pooled) database endpoint, as Hyperdrive provides its own pooling layer.

    Supported database providers in Alchemy include:

    • Neon: Serverless Postgres with copy-on-write branching.
    • PlanetScale (Postgres): Managed Postgres with branch-per-PR workflows.
    • PlanetScale (MySQL): Vitess-backed MySQL with branching.

  6. What is Effect RPC and when to use it

    main

    Effect RPC is a schema-first RPC system designed for trust boundaries (e.g., a web app or external service calling into your stack). It ensures every request and response is validated against declared payload, success, and error Schemas.

    When to use it:

    • When data crosses a trust boundary and requires runtime validation.
    • When you need typed errors that the client can catchTag on (rather than raw HTTP status codes).

    When NOT to use it:

    • For internal service-to-service calls. In these cases, use Schemaless RPC to avoid the per-request performance cost of schema decoding/encoding and runtime validation.

  7. What is SageMaker HyperPod?

    main

    SageMaker HyperPod is a persistent fleet for ML training and inference on AWS. It consists of accelerated instances with automatic health checks, faulty-node replacement, and deep GPU health checks. Unlike ECS or EKS which run application containers, HyperPod is designed for distributed training and remains active between jobs.

    Core Primitives

    • Cluster: The fleet of instances, orchestrated by either Slurm (default) or an EKS cluster.
    • Instance Group: A set of identical instances (e.g., a controller group or worker group) defined by instance type, count, execution role, and a lifecycle script.
    • Lifecycle Script: An on_create.sh script stored in S3 that runs on every node during boot to install schedulers, mount file systems (like FSx), or configure observability.
    • Task Governance (EKS only): Uses scheduler policies (priority classes) and per-team compute quotas to arbitrate fleet access between teams.

  8. What is Effect HTTP?

    main

    Effect HTTP (effect/unstable/httpapi) provides schema-validated REST endpoints with an RPC-like typed interface. It is designed for 'trust boundaries' where you need to expose data to web apps or external services that use plain HTTP clients.

    When to use Effect HTTP vs others:

    • Use Effect HTTP when consumers are not Effect/TypeScript programs and need standard REST (URLs, path params, query strings, headers, bodies).
    • Use Effect RPC when consumers are also Effect programs and you want a leaner wire protocol.
    • Use Schemaless RPC for internal service-to-service calls where you want to avoid the performance cost of per-request schema encoding/decoding.

  9. What is a Sink and how does it work?

    main

    A Sink is the write-side dual of an Event Source. It is a Binding that exposes a resource as an Effect Sink.

    While an Event Source provides records as a Stream, a Sink accepts a Stream and drains it into the resource's batch API (such as SendMessageBatch, PublishBatch, or PutRecords). Sinks automatically handle batching and emit the minimal, least-privilege IAM policies required for the specific resource ARN.

  10. What is an Action and when to use it

    main

    An Action is a node in the dependency graph that executes an arbitrary Effect during the apply phase of a deployment.

    Unlike a Resource, an Action has no provider lifecycle (no replace, read, or delete). The engine determines whether to run the Action by comparing the JSON-serialized SHA-256 hash of its resolved inputs against the last persisted hash. If they match, the Action is skipped; if they differ, it runs.

    Use cases for Actions:

    • Seeding a database.
    • Posting release notifications.
    • Generating and uploading artifacts.
    • Invalidating CDN caches.
    • Running migration checks.

  11. Understand Prisma Branches

    main

    A Prisma.Branch is a grouping mechanism within a project that organizes databases and compute apps under git-style names. It uses two primary properties to manage environment behavior:

    • role: Determines whether Compute resolves production or preview environment variables. The first branch created in a project is automatically assigned the immutable production role. All subsequent branches are assigned the preview role.
    • isDefault: A boolean flag that identifies which branch new resources should use when a branch is not explicitly specified.

    Note on Promotion: Promoting a branch (setting isDefault: true) changes its isDefault status but does not change its role. A promoted preview branch remains in the preview class for environment variable resolution.

    import * as Prisma from "alchemy/Prisma";

const branch = yield* Prisma.Branch("preview", { project });

  12. Understand Alchemy Profiles

    main

    A profile is a named bundle of cloud credentials stored locally in ~/.alchemy/profiles.json. Profiles manage how alchemy authenticates to your cloud providers.

    They are independent from Stages (which control what is deployed). Use profiles to:

    • Separate work and personal accounts.
    • Use different IAM roles for prod vs dev.
    • Rotate or refresh tokens without affecting other configurations.