The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import { AlchemyContext } from "alchemy/AlchemyContext"; |
| 2 | import type { MemoOptions } from "alchemy/Command/Memo"; |
| 3 | import * as DNS from "alchemy/DNS/Adapter"; |
| 4 | import * as Output from "alchemy/Output"; |
| 5 | import { ProviderModePolicy } from "alchemy/ProviderMode"; |
| 6 | import type { WebsiteAssetsProps } from "alchemy/Website/assets"; |
| 7 | import { Server, type ServerDevProps } from "alchemy/Website/Server"; |
| 8 | import * as Effect from "effect/Effect"; |
| 9 | import * as Redacted from "effect/Redacted"; |
| 10 | import type { Branch } from "../Branch.ts"; |
| 11 | import type { BranchScope } from "../BranchScope.ts"; |
| 12 | import { CustomDomain } from "../CustomDomain.ts"; |
| 13 | import { Function, type FunctionCommonProps } from "../Function.ts"; |
| 14 | import { Project } from "../Project.ts"; |
| 15 | import type { Providers } from "../Providers.ts"; |
| 16 | import { WebsiteArtifact } from "./Artifact.ts"; |
| 17 | |
| 18 | /** Deployment controls; the composition owns code, environment, and runtime wiring. */ |
| 19 | export type WebsiteFunctionOptions = Pick<FunctionCommonProps, "slug" | "name">; |
| 20 | |
| 21 | /** Shared framework configuration, independent of backend scope. */ |
| 22 | export interface FrameworkSiteOptions { |
| 23 | /** Application directory containing package.json and framework configuration. @default "." */ |
| 24 | rootDir?: string; |
| 25 | /** Build input hashing. Set false to rebuild every deployment. @default true */ |
| 26 | memo?: MemoOptions | boolean; |
| 27 | /** Build, development, and runtime values. Public framework prefixes are browser-visible; Redacted does not prevent build tools from embedding a value. */ |
| 28 | env?: Record<string, string | Redacted.Redacted<string> | Output.Output<string | undefined>>; |
| 29 | /** Static-file routing within the Function, not a separate CDN. */ |
| 30 | assets?: WebsiteAssetsProps; |
| 31 | /** Native framework dev server, including external-server mode. */ |
| 32 | dev?: ServerDevProps; |
| 33 | /** |
| 34 | * Custom hostname registered with `Neon.CustomDomain`. |
| 35 | * |
| 36 | * A string (or `{ name }`) leaves DNS to you: publish `domain.cnameTarget` |
| 37 | * as a DNS-only CNAME and verify HTTPS separately. Set `dns` (e.g. |
| 38 | * `{ name: "www.example.com", dns: Cloudflare.DNS.Adapter() }`) to publish |
| 39 | * that CNAME through the DNS host. See |
| 40 | * [DNS Adapters](/infrastructure-as-code/dns-adapters). |
| 41 | */ |
| 42 | domain?: WebsiteDomain; |
| 43 | /** Supported Function controls; memory, listening ports, and Docker options are not available. */ |
| 44 | function?: WebsiteFunctionOptions; |
| 45 | } |
| 46 | |
| 47 | /** Custom hostname of a Neon website: the hostname, or `{ name, dns }`. */ |
| 48 | export type WebsiteDomain = |
| 49 | | string |
| 50 | | { |
| 51 | /** Hostname, e.g. `www.example.com`. */ |
| 52 | name: string; |
| 53 | /** |
| 54 | * DNS host that publishes the CNAME to the domain's `cnameTarget` |
| 55 | * (see [DNS Adapters](/infrastructure-as-code/dns-adapters)), e.g. |
| 56 | * `Cloudflare.DNS.Adapter()`. Neon requires the record to be |
| 57 | * DNS-only, so do not proxy it. Omitted: publish it yourself. |
| 58 | */ |
| 59 | dns?: DNS.DnsConfig; |
| 60 | }; |
| 61 | |
| 62 | /** The hostname of a {@link WebsiteDomain}. */ |
| 63 | export const websiteDomainName = (domain: WebsiteDomain | undefined): string | undefined => |
| 64 | domain === undefined || typeof domain === "string" ? domain : domain.name; |
| 65 | |
| 66 | /** Scope references are forwarded to the composed resources without resolution. */ |
| 67 | export type WebsiteScope = |
| 68 | | { branch: Branch | NonNullable<BranchScope["branch"]>; project?: never } |
| 69 | | { project: Project | NonNullable<BranchScope["project"]>; branch?: never } |
| 70 | | { project?: never; branch?: never }; |
| 71 | |
| 72 | /** Explicit branch or project, or an Ohio project owned only on live deployments. */ |
| 73 | export type FrameworkSiteProps = FrameworkSiteOptions & WebsiteScope; |
| 74 | |
| 75 | /** Outputs of a Neon framework or static website. */ |
| 76 | export interface Website { |
| 77 | /** Native dev URL locally, otherwise the Function or configured custom-domain URL. */ |
| 78 | url: string | Output.Output<string | undefined> | undefined; |
| 79 | /** Function serving the artifact; absent during native development. */ |
| 80 | function: Function | undefined; |
| 81 | /** Explicit or owned project reference; explicit references are preserved locally. */ |
| 82 | project: WebsiteScope["project"]; |
| 83 | /** Explicit branch reference, preserved locally without transferring ownership. */ |
| 84 | branch: WebsiteScope["branch"]; |
| 85 | /** Custom-domain registration and DNS target; absent during native development. */ |
| 86 | domain: CustomDomain | undefined; |
| 87 | } |
| 88 | |
| 89 | /** Internal framework-to-Fetch target wiring. */ |
| 90 | export interface FrameworkSiteConfig { |
| 91 | /** Framework integration module. */ |
| 92 | framework: string; |
| 93 | /** Neon Fetch deploy-target module. */ |
| 94 | target: string; |
| 95 | /** Serializable native framework overrides. */ |
| 96 | options?: Record<string, unknown>; |
| 97 | /** Next.js keeps output and configuration beside its entrypoint. */ |
| 98 | layout?: "output" | "next"; |
| 99 | /** Default unmatched-path behavior. */ |
| 100 | notFoundHandling?: "none" | "spa" | "404-page"; |
| 101 | /** Default extensionless HTML behavior. */ |
| 102 | htmlHandling?: "none" | "drop-trailing-slash"; |
| 103 | } |
| 104 | |
| 105 | /** Unwrap build values without changing the runtime's redacted props. */ |
| 106 | export const websiteBuildEnv = (env: FrameworkSiteProps["env"]) => |
| 107 | env === undefined |
| 108 | ? undefined |
| 109 | : Object.fromEntries( |
| 110 | Object.entries(env).map(([key, value]) => [ |
| 111 | key, |
| 112 | Redacted.isRedacted(value) ? Redacted.value(value) : value, |
| 113 | ]), |
| 114 | ); |
| 115 | |
| 116 | /** Live composition; explicit projects and branches remain independently owned. */ |
| 117 | export const deployWebsite = Effect.fn(function* ( |
| 118 | props: Omit<FrameworkSiteOptions, "dev"> & WebsiteScope, |
| 119 | artifact: WebsiteArtifact, |
| 120 | ): Effect.fn.Return<Website, never, Providers> { |
| 121 | const project = props.branch |
| 122 | ? undefined |
| 123 | : (props.project ?? |
| 124 | (yield* Project("Project", { |
| 125 | // Validate the artifact before provisioning an implicit backend. |
| 126 | region: Output.map(artifact.hash, () => "aws-us-east-2" as const), |
| 127 | }))); |
| 128 | const scope = props.branch !== undefined ? { branch: props.branch } : { project: project! }; |
| 129 | const fn = yield* Function("Function", { |
| 130 | ...props.function, |
| 131 | ...scope, |
| 132 | artifact: { zip: artifact.artifactPath }, |
| 133 | env: { ...props.env, NODE_ENV: "production" }, |
| 134 | }); |
| 135 | const domainName = websiteDomainName(props.domain); |
| 136 | const domain = domainName |
| 137 | ? yield* CustomDomain("Domain", { function: fn, hostname: domainName }) |
| 138 | : undefined; |
| 139 | if (domain !== undefined && typeof props.domain === "object" && props.domain.dns !== undefined) { |
| 140 | const dns = yield* DNS.resolve(props.domain.dns); |
| 141 | // Not "Domain": Route 53 names a CNAME alias by the bare id, which |
| 142 | // would collide with the CustomDomain above. |
| 143 | yield* dns.alias("DomainAlias", { |
| 144 | name: props.domain.name, |
| 145 | target: { hostname: domain.cnameTarget }, |
| 146 | }); |
| 147 | } |
| 148 | return { |
| 149 | url: domain ? domain.url : fn.url, |
| 150 | function: fn, |
| 151 | project, |
| 152 | branch: props.branch, |
| 153 | domain, |
| 154 | }; |
| 155 | }); |
| 156 | |
| 157 | /** Compose native development or a production Fetch build with a traced artifact. */ |
| 158 | export const makeFrameworkSite = Effect.fn(function* ( |
| 159 | _id: string, |
| 160 | props: FrameworkSiteProps, |
| 161 | config: FrameworkSiteConfig, |
| 162 | ) { |
| 163 | const context = yield* AlchemyContext; |
| 164 | const remote = yield* ProviderModePolicy; |
| 165 | if (props.project !== undefined && props.branch !== undefined) { |
| 166 | return yield* Effect.die(new Error("Specify branch or project, never both.")); |
| 167 | } |
| 168 | const handling = props.assets?.notFoundHandling; |
| 169 | const targetConfig = { |
| 170 | notFoundHandling: |
| 171 | handling === "single-page-application" ? "spa" : (handling ?? config.notFoundHandling), |
| 172 | htmlHandling: props.assets?.htmlHandling ?? config.htmlHandling, |
| 173 | }; |
| 174 | const build = yield* Server("Build", { |
| 175 | framework: config.framework, |
| 176 | target: config.target, |
| 177 | root: props.rootDir, |
| 178 | env: websiteBuildEnv(props.env), |
| 179 | options: { ...config.options, ...targetConfig, targetConfig }, |
| 180 | memo: props.memo, |
| 181 | dev: props.dev, |
| 182 | }); |
| 183 | if (context.dev && remote !== true) { |
| 184 | return { |
| 185 | url: build.url, |
| 186 | function: undefined, |
| 187 | project: props.project, |
| 188 | branch: props.branch, |
| 189 | domain: undefined, |
| 190 | } satisfies Website; |
| 191 | } |
| 192 | const requiredPath = (value: string | undefined) => |
| 193 | value === undefined |
| 194 | ? Effect.die(new Error(`The ${config.framework} build produced no Neon Fetch output.`)) |
| 195 | : Effect.succeed(value); |
| 196 | const artifact = yield* WebsiteArtifact("Artifact", { |
| 197 | root: props.rootDir ?? ".", |
| 198 | distDir: Output.mapEffect(requiredPath)(build.distDir), |
| 199 | serverEntry: Output.mapEffect(requiredPath)(build.serverEntry), |
| 200 | layout: config.layout, |
| 201 | buildHash: build.hash.output, |
| 202 | }); |
| 203 | return yield* deployWebsite(props, artifact); |
| 204 | }); |