cloud-run-functions 0.1.4 → 0.2.1

package/config.schema.json

@@ -55,10 +55,7 @@
       "oneOf": [
         {
           "description": "The adapter wraps your Cloud Run functions at runtime, allowing you to write them with a platform-agnostic HTTP framework, like Hattip.\n\nSet this to \"node\" to skip using an adapter, in which case, your functions should conform to what @google-cloud/functions-framework expects.\n\n@default \"node\"",
-          "enum": [
-            "hattip",
-            "node"
-          ]
+          "enum": ["hattip", "node"]
         },
         {
           "type": "null"
@@ -91,4 +88,4 @@
     }
   },
   "required": []
-}
+}

package/dist/chunk-L3GFRAQX.js

@@ -0,0 +1,125 @@
+import {
+  getFunctionFilter,
+  loadConfig
+} from "./chunk-MOB3GBJW.js";
+
+// src/tools/build.ts
+import esbuild from "esbuild";
+import { findUpSync } from "find-up-simple";
+import fs from "node:fs";
+import path from "node:path";
+import { glob } from "tinyglobby";
+var virtualModuleId = "virtual:cloud-run-functions";
+var virtualModuleNamespace = "crf-functions";
+async function build(root, { define, outdir } = {}) {
+  const workingDir = process.cwd();
+  const searchDir = path.resolve(workingDir, root ?? "");
+  const config = loadConfig(searchDir);
+  const functionsRoot = config.configDir ? path.resolve(config.configDir, config.root ?? "") : searchDir;
+  const functionFilter = getFunctionFilter(config);
+  const adapter = config.adapter ?? "node";
+  const entries = await glob(functionFilter.globs, {
+    cwd: functionsRoot,
+    onlyFiles: true
+  });
+  const entryPoints = Array.from(
+    new Set(entries.map((entry) => entry.split(path.sep).join("/")))
+  );
+  const routes = entryPoints.map((entry) => {
+    const name = entry.replace(functionFilter.suffixPattern, "");
+    return {
+      entry,
+      name,
+      path: "/" + name
+    };
+  }).sort((a, b) => a.path.localeCompare(b.path));
+  const seenPaths = /* @__PURE__ */ new Set();
+  for (const route of routes) {
+    if (seenPaths.has(route.path)) {
+      throw new Error(`Duplicate route detected: ${route.path}`);
+    }
+    seenPaths.add(route.path);
+  }
+  const outputDir = path.resolve(workingDir, outdir ?? "dist");
+  fs.mkdirSync(outputDir, { recursive: true });
+  const packageDir = findUpSync("dist", {
+    cwd: import.meta.dirname,
+    type: "directory"
+  });
+  if (!packageDir) {
+    throw new Error("Unable to locate the package dist directory.");
+  }
+  const source = path.join(packageDir, "targets/build.js");
+  const outfile = path.join(outputDir, "index.js");
+  const result = await esbuild.build({
+    entryPoints: [source],
+    absWorkingDir: functionsRoot,
+    outfile,
+    define,
+    bundle: true,
+    format: "cjs",
+    platform: "node",
+    packages: "bundle",
+    sourcemap: true,
+    sourcesContent: false,
+    logOverride: {
+      "empty-glob": "silent"
+    },
+    external: ["@google-cloud/functions-framework"],
+    plugins: [
+      {
+        name: "crf-virtual-functions",
+        setup(build2) {
+          const filter = new RegExp(
+            `^${virtualModuleId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}$`
+          );
+          build2.onResolve({ filter }, () => ({
+            path: virtualModuleId,
+            namespace: virtualModuleNamespace
+          }));
+          build2.onLoad(
+            { filter: /.*/, namespace: virtualModuleNamespace },
+            () => ({
+              contents: createVirtualModule({
+                routes,
+                adapter
+              }),
+              loader: "js",
+              resolveDir: functionsRoot
+            })
+          );
+        }
+      }
+    ]
+  });
+  console.log(
+    `[esbuild] Bundled ${routes.length} function${routes.length === 1 ? "" : "s"} into ${outfile}`
+  );
+  return result;
+}
+function createVirtualModule({
+  routes,
+  adapter
+}) {
+  const imports = routes.map((route, index) => {
+    const importPath = route.entry.startsWith(".") ? route.entry : `./${route.entry}`;
+    return `import * as route${index} from ${JSON.stringify(importPath)};`;
+  });
+  const routeEntries = routes.map(
+    (route, index) => `  { name: ${JSON.stringify(route.name)}, path: ${JSON.stringify(
+      route.path
+    )}, module: route${index} },`
+  );
+  return [
+    ...imports,
+    `export const adapter = ${JSON.stringify(adapter)};`,
+    "export const routes = [",
+    ...routeEntries,
+    "];",
+    ""
+  ].join("\n");
+}
+
+export {
+  build
+};

package/dist/chunk-MOB3GBJW.js

@@ -0,0 +1,109 @@
+import {
+  dedent
+} from "./chunk-SPF3AMMV.js";
+
+// src/common/functionFilter.ts
+import path from "node:path";
+function getFunctionFilter(options) {
+  const functionGlobs = [];
+  const functionSuffixes = /* @__PURE__ */ new Set();
+  const requiredSuffix = options.entrySuffix?.replace(/^\.?/, ".") ?? "";
+  for (const glob of options.globs ?? ["**/*"]) {
+    let ext = path.extname(glob);
+    if (ext) {
+      functionSuffixes.add(requiredSuffix + ext);
+      functionGlobs.push(
+        requiredSuffix ? glob.replace(ext, requiredSuffix + ext) : glob
+      );
+      continue;
+    }
+    for (ext of options.extensions ?? [".ts", ".js"]) {
+      ext = requiredSuffix + ext;
+      functionSuffixes.add(ext);
+      functionGlobs.push(glob + ext);
+    }
+  }
+  const suffixPattern = new RegExp(
+    `(${Array.from(functionSuffixes, (e) => e.replace(/\./g, "\\.")).sort((a, b) => b.length - a.length).join("|")})$`
+  );
+  return {
+    globs: functionGlobs,
+    suffixPattern
+  };
+}
+
+// src/config/index.ts
+import * as z2 from "@zod/mini";
+import Joycon from "joycon";
+import path2 from "node:path";
+
+// src/config/schema.ts
+import * as z from "@zod/mini";
+var configSchema = z.partial(
+  z.interface({
+    root: z.string().register(z.globalRegistry, {
+      description: dedent`
+        The base directory when searching for entry points.
+
+        Defaults to the config directory (or if no config file is found, the current working directory).
+      `
+    }),
+    globs: z.array(z.string()).register(z.globalRegistry, {
+      description: dedent`
+        The globs determine which directories are searched for entry points. Only ".ts" and ".js" files are matched, so you're not required to include them in the globs.
+
+        By default all directories in the "root" are searched.
+      `
+    }),
+    extensions: z.array(z.string()).register(z.globalRegistry, {
+      description: dedent`
+        The extensions to match for entry points.
+
+        @default [".ts", ".js"]
+      `
+    }),
+    entrySuffix: z.string().register(z.globalRegistry, {
+      description: dedent`
+        The entry suffix should be a string like ".task" or ".function" which must be present in the file name (before the extension) or else that file will be ignored when scanning for entry points.
+
+        It can also be an empty string.
+      `
+    }),
+    adapter: z.enum(["hattip", "node"]).register(z.globalRegistry, {
+      description: dedent`
+        The adapter wraps your Cloud Run functions at runtime, allowing you to write them with a platform-agnostic HTTP framework, like Hattip.
+
+        Set this to "node" to skip using an adapter, in which case, your functions should conform to what @google-cloud/functions-framework expects.
+
+        @default "node"
+      `
+    }),
+    maxInstanceConcurrency: z.union([z.number(), z.record(z.string(), z.number())]).register(z.globalRegistry, {
+      description: dedent`
+          The maximum number of instances (per function) that can be run concurrently. You can either set the same limit for all functions or set a different limit for each function.
+
+          @default 5
+        `
+    })
+  })
+);
+
+// src/config/index.ts
+var joycon = new Joycon();
+function loadConfig(cwd) {
+  const result = joycon.loadSync(["crf.config.json"], cwd);
+  if (!result.path) {
+    return {
+      configDir: null
+    };
+  }
+  return {
+    ...z2.parse(configSchema, result.data),
+    configDir: path2.dirname(result.path)
+  };
+}
+
+export {
+  getFunctionFilter,
+  loadConfig
+};

package/dist/chunk-XHFBJ7D2.js

@@ -0,0 +1,25 @@
+// src/tools/preview.ts
+import { findUpSync } from "find-up-simple";
+import path from "node:path";
+import $ from "picospawn";
+function preview({ outDir, ...options } = {}) {
+  const packageDir = findUpSync("dist", {
+    cwd: import.meta.dirname,
+    type: "directory"
+  });
+  const binDir = path.resolve(packageDir, "../node_modules/.bin");
+  const sourceDir = path.resolve(process.cwd(), outDir ?? "dist");
+  const source = path.join(sourceDir, "index.js");
+  return $("functions-framework --target=build --source %s", [source], {
+    stdio: "inherit",
+    ...options,
+    env: {
+      ...options.env ?? process.env,
+      PATH: `${binDir}:${process.env.PATH}`
+    }
+  });
+}
+
+export {
+  preview
+};

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { BuildOptions, BundleOptions, build } from './tools/build.js';
 export { DevOptions, dev } from './tools/dev.js';
+export { PreviewOptions, preview } from './tools/preview.js';
+import 'esbuild';
 import 'picospawn';
-import './tools/build.js';

package/dist/index.js

@@ -1,6 +1,16 @@
+import {
+  build
+} from "./chunk-L3GFRAQX.js";
+import "./chunk-MOB3GBJW.js";
+import "./chunk-SPF3AMMV.js";
 import {
   dev
 } from "./chunk-DG37B63B.js";
+import {
+  preview
+} from "./chunk-XHFBJ7D2.js";
 export {
-  dev
+  build,
+  dev,
+  preview
 };

package/dist/main.d.ts

@@ -1,2 +1 @@
-
-export {  }
+#!/usr/bin/env node

package/dist/main.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import {
   objectify
 } from "./chunk-SPF3AMMV.js";
@@ -14,6 +15,20 @@ import {
   string,
   subcommands
 } from "cmd-ts";
+
+// src/common/parseDefines.ts
+function parseDefines(define) {
+  if (!define) {
+    return void 0;
+  }
+  return objectify(
+    define.map((d) => d.split(":")),
+    ([key]) => key,
+    ([, value]) => value ? isNaN(parseFloat(value)) ? JSON.stringify(value) : value : ""
+  );
+}
+
+// src/main.ts
 var dev = command({
   name: "dev",
   description: "Start the development server",
@@ -40,33 +55,62 @@ var dev = command({
     const { dev: dev2 } = await import("./tools/dev.js");
     await dev2(root, {
       port,
-      define: define && objectify(
-        define.map((d) => d.split(":")),
-        ([key]) => key,
-        ([, value]) => value ? isNaN(parseFloat(value)) ? JSON.stringify(value) : value : ""
-      )
+      define: parseDefines(define)
     });
   }
 });
 var build = command({
   name: "build",
-  description: "Generate a bundle for each function",
+  description: "Bundle your functions for deployment",
   args: {
     root: positional({
       type: optional(string),
       displayName: "root",
       description: "Directory to search for function entrypoints"
+    }),
+    outdir: option({
+      type: optional(string),
+      long: "outdir",
+      short: "o",
+      description: "The directory to write bundled output to"
+    }),
+    define: multioption({
+      type: optional(array(string)),
+      long: "define",
+      short: "d",
+      description: "Statically replace specific variables in the source code"
+    })
+  },
+  async handler({ root, outdir, define }) {
+    const { build: build2 } = await import("./tools/build.js");
+    await build2(root, {
+      outdir,
+      define: parseDefines(define)
+    });
+  }
+});
+var preview = command({
+  name: "preview",
+  description: "Preview bundled functions locally",
+  args: {
+    outDir: option({
+      type: optional(string),
+      long: "outDir",
+      short: "o",
+      description: "The directory containing the bundled output"
     })
   },
-  async handler() {
-    throw new Error("Not implemented");
+  async handler({ outDir }) {
+    const { preview: preview2 } = await import("./tools/preview.js");
+    await preview2({ outDir });
   }
 });
 var cli = subcommands({
   name: "cloud-run-functions",
   cmds: {
     dev,
-    build
+    build,
+    preview
   }
 });
 await run(cli, process.argv.slice(2));

package/dist/targets/build.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/targets/build.js

@@ -0,0 +1,53 @@
+// src/targets/build.ts
+import "source-map-support/register.js";
+import functions from "@google-cloud/functions-framework";
+import { adapter, routes } from "virtual:cloud-run-functions";
+var routesByPath = new Map(routes.map((route) => [route.path, route]));
+var handlerCache = /* @__PURE__ */ new Map();
+function unwrapHandler(module) {
+  let handler = module;
+  while (handler && typeof handler !== "function") {
+    handler = handler.default;
+  }
+  return typeof handler === "function" ? handler : null;
+}
+async function getHandler(route) {
+  const cached = handlerCache.get(route.path);
+  if (cached) {
+    return cached;
+  }
+  let handler = unwrapHandler(route.module);
+  if (!handler) {
+    throw new Error(`Task ${route.name} is not a function.`);
+  }
+  switch (adapter) {
+    case "hattip": {
+      const { createMiddleware } = await import("@hattip/adapter-node");
+      handler = createMiddleware(handler);
+      break;
+    }
+  }
+  handlerCache.set(route.path, handler);
+  return handler;
+}
+async function match(url) {
+  const route = routesByPath.get(url.pathname);
+  if (!route) {
+    return null;
+  }
+  return getHandler(route);
+}
+functions.http("build", async (req, res) => {
+  const url = new URL(req.url, "http://" + req.headers.host);
+  const handler = await match(url);
+  if (handler) {
+    try {
+      await handler(req, res);
+    } catch (error) {
+      console.error(error);
+      res.status(500).end();
+    }
+  } else {
+    res.status(404).end();
+  }
+});

package/dist/targets/dev.js

@@ -1,5 +1,8 @@
 import {
-  dedent,
+  getFunctionFilter,
+  loadConfig
+} from "../chunk-MOB3GBJW.js";
+import {
   isNumber,
   timeout,
   toResult
@@ -13,7 +16,7 @@ import { findUpSync } from "find-up-simple";
 import fs2 from "node:fs";
 import { Module } from "node:module";
 import os from "node:os";
-import path3 from "node:path";
+import path from "node:path";
 
 // src/common/emptyDir.ts
 import fs from "node:fs";
@@ -23,122 +26,21 @@ function emptyDir(dir) {
   return dir;
 }
 
-// src/common/functionFilter.ts
-import path from "node:path";
-function getFunctionFilter(options) {
-  const functionGlobs = [];
-  const functionSuffixes = /* @__PURE__ */ new Set();
-  const requiredSuffix = options.entrySuffix?.replace(/^\.?/, ".") ?? "";
-  for (const glob of options.globs ?? ["**/*"]) {
-    let ext = path.extname(glob);
-    if (ext) {
-      functionSuffixes.add(requiredSuffix + ext);
-      functionGlobs.push(
-        requiredSuffix ? glob.replace(ext, requiredSuffix + ext) : glob
-      );
-      continue;
-    }
-    for (ext of options.extensions ?? [".ts", ".js"]) {
-      ext = requiredSuffix + ext;
-      functionSuffixes.add(ext);
-      functionGlobs.push(glob + ext);
-    }
-  }
-  const suffixPattern = new RegExp(
-    `(${Array.from(functionSuffixes, (e) => e.replace(/\./g, "\\.")).sort((a, b) => b.length - a.length).join("|")})$`
-  );
-  return {
-    globs: functionGlobs,
-    suffixPattern
-  };
-}
-
 // src/common/hash.ts
 import crypto from "node:crypto";
 function hash(data, len) {
   return crypto.createHash("sha256").update(data).digest("hex").slice(0, len);
 }
 
-// src/config/index.ts
-import * as z2 from "@zod/mini";
-import Joycon from "joycon";
-import path2 from "node:path";
-
-// src/config/schema.ts
-import * as z from "@zod/mini";
-var configSchema = z.partial(
-  z.interface({
-    root: z.string().register(z.globalRegistry, {
-      description: dedent`
-        The base directory when searching for entry points.
-
-        Defaults to the config directory (or if no config file is found, the current working directory).
-      `
-    }),
-    globs: z.array(z.string()).register(z.globalRegistry, {
-      description: dedent`
-        The globs determine which directories are searched for entry points. Only ".ts" and ".js" files are matched, so you're not required to include them in the globs.
-
-        By default all directories in the "root" are searched.
-      `
-    }),
-    extensions: z.array(z.string()).register(z.globalRegistry, {
-      description: dedent`
-        The extensions to match for entry points.
-
-        @default [".ts", ".js"]
-      `
-    }),
-    entrySuffix: z.string().register(z.globalRegistry, {
-      description: dedent`
-        The entry suffix should be a string like ".task" or ".function" which must be present in the file name (before the extension) or else that file will be ignored when scanning for entry points.
-
-        It can also be an empty string.
-      `
-    }),
-    adapter: z.enum(["hattip", "node"]).register(z.globalRegistry, {
-      description: dedent`
-        The adapter wraps your Cloud Run functions at runtime, allowing you to write them with a platform-agnostic HTTP framework, like Hattip.
-
-        Set this to "node" to skip using an adapter, in which case, your functions should conform to what @google-cloud/functions-framework expects.
-
-        @default "node"
-      `
-    }),
-    maxInstanceConcurrency: z.union([z.number(), z.record(z.string(), z.number())]).register(z.globalRegistry, {
-      description: dedent`
-          The maximum number of instances (per function) that can be run concurrently. You can either set the same limit for all functions or set a different limit for each function.
-
-          @default 5
-        `
-    })
-  })
-);
-
-// src/config/index.ts
-var joycon = new Joycon();
-function loadConfig(cwd) {
-  const result = joycon.loadSync(["crf.config.json"], cwd);
-  if (!result.path) {
-    return {
-      configDir: null
-    };
-  }
-  return {
-    ...z2.parse(configSchema, result.data),
-    configDir: path2.dirname(result.path)
-  };
-}
-
 // src/targets/dev.ts
 async function createBuild() {
   const options = JSON.parse(process.env.CRF_OPTIONS);
-  const searchDir = path3.resolve(options.workingDir, options.searchDir ?? "");
+  const searchDir = path.resolve(options.workingDir, options.searchDir ?? "");
   const config = loadConfig(searchDir);
-  const root = config.configDir ? path3.resolve(config.configDir, config.root ?? "") : searchDir;
+  const root = config.configDir ? path.resolve(config.configDir, config.root ?? "") : searchDir;
   const functionFilter = getFunctionFilter(config);
   const cacheDir = emptyDir(
-    path3.join(
+    path.join(
       fs2.realpathSync(os.tmpdir()),
       "cloud-run-functions-" + hash(root, 8)
     )
@@ -240,7 +142,7 @@ async function createBuild() {
           taskState.running++;
           taskStates.set(taskName, taskState);
           const require2 = Module.createRequire(import.meta.filename);
-          let taskHandler = require2(path3.join(root, file));
+          let taskHandler = require2(path.join(root, file));
           while (taskHandler && typeof taskHandler !== "function") {
             taskHandler = taskHandler.default;
           }

package/dist/tools/build.d.ts

@@ -1,3 +1,5 @@
+import esbuild from 'esbuild';
+
 type BuildOptions = {
     /**
      * Statically replace specific variables in the source code.
@@ -13,5 +15,32 @@ type BuildOptions = {
      */
     define?: Record<string, string>;
 };
+type BundleOptions = BuildOptions & {
+    /**
+     * The directory to write the bundled output to.
+     * @default "dist"
+     */
+    outdir?: string;
+};
+declare function build(root?: string, { define, outdir }?: BundleOptions): Promise<esbuild.BuildResult<{
+    entryPoints: string[];
+    absWorkingDir: string;
+    outfile: string;
+    define: Record<string, string> | undefined;
+    bundle: true;
+    format: "cjs";
+    platform: "node";
+    packages: "bundle";
+    sourcemap: true;
+    sourcesContent: false;
+    logOverride: {
+        'empty-glob': "silent";
+    };
+    external: string[];
+    plugins: {
+        name: string;
+        setup(build: esbuild.PluginBuild): void;
+    }[];
+}>>;
 
-export type { BuildOptions };
+export { type BuildOptions, type BundleOptions, build };

package/dist/tools/build.js

@@ -0,0 +1,8 @@
+import {
+  build
+} from "../chunk-L3GFRAQX.js";
+import "../chunk-MOB3GBJW.js";
+import "../chunk-SPF3AMMV.js";
+export {
+  build
+};

package/dist/tools/dev.d.ts

@@ -1,6 +1,7 @@
 import * as picospawn from 'picospawn';
 import { PicospawnOptions } from 'picospawn';
 import { BuildOptions } from './build.js';
+import 'esbuild';
 
 interface DevOptions extends PicospawnOptions, BuildOptions {
     /**

package/dist/tools/preview.d.ts

@@ -0,0 +1,16 @@
+import * as picospawn from 'picospawn';
+import { PicospawnOptions } from 'picospawn';
+
+interface PreviewOptions extends PicospawnOptions {
+    /**
+     * The directory containing the bundled output.
+     * @default "dist"
+     */
+    outDir?: string;
+}
+/**
+ * Start the preview server for the bundled output.
+ */
+declare function preview({ outDir, ...options }?: PreviewOptions): picospawn.PicospawnPromise<unknown>;
+
+export { type PreviewOptions, preview };

package/dist/tools/preview.js

@@ -0,0 +1,6 @@
+import {
+  preview
+} from "../chunk-XHFBJ7D2.js";
+export {
+  preview
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cloud-run-functions",
   "type": "module",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "bin": "./dist/main.js",
   "exports": {
     "types": "./dist/index.d.ts",

package/readme.md

@@ -1,33 +1,166 @@
 # cloud-run-functions
 
-> ⚠️ This project is not ready for production use.
+File-based routing plus local dev and bundling for `@google-cloud/functions-framework`.
 
-Enhances the `@google-cloud/functions-framework` package with "hot reloading" (for local development) and a bundler (for deployment).
+You point it at a directory of `.ts` or `.js` files. \
+Each file becomes an HTTP route and its default export is treated as the handler.
 
+## Install
+
+`@google-cloud/functions-framework` is required because this package runs it under the hood.
+
+```sh
+pnpm add -D cloud-run-functions @google-cloud/functions-framework
+```
+
+Optional:
+
+```sh
+pnpm add -D dotenv
+pnpm add -D @hattip/adapter-node
+```
+
+## Quick start
+
+Create a function file:
+
+`functions/hello.ts`
+
+```ts
+export default (req, res) => {
+  res.status(200).send('hello')
+}
+```
+
+Run the dev server:
+
+```sh
+pnpx cloud-run-functions dev functions
+```
+
+Call it:
+
+```sh
+curl http://localhost:8080/hello
+```
+
+## Routing
+
+- A file path becomes a URL path
+- `functions/hello.ts` becomes `/hello`
+- `functions/users/create.ts` becomes `/users/create`
+- Your file should default export a function handler
+- If you set `entrySuffix` to `.task`, then `hello.task.ts` becomes `/hello`
+
+## CLI
+
+The binary name is `cloud-run-functions`.
+
+### dev
+
+Start the development server with hot reload.
+
+```sh
+npx cloud-run-functions dev [root]
 ```
-pnpm add cloud-run-functions -D
+
+- `root` is the directory to search for function entrypoints. Default is the current working directory
+- `--port, -p <port>` sets the port. Default is `8080`
+- `--define, -d <key:value>` can be repeated. It passes `define` values to esbuild
+
+### build
+
+Bundle your functions for deployment.
+
+```sh
+npx cloud-run-functions build [root]
 ```
 
-## Development server
+- `root` is the directory to search for function entrypoints. Default is the current working directory
+- `--outdir, -o <dir>` sets the output directory. Default is `dist`
+- `--define, -d <key:value>` can be repeated. It passes `define` values to esbuild
+
+Output:
 
-The dev server uses the `@google-cloud/functions-framework` package to run your functions locally. We handle _transpiling_ and _hot reloading_ for you. Just tell the dev server where to find your functions.
+- Writes `index.js` and sourcemaps into `outdir`
+- Run it with the Functions Framework using the `build` target
+
+Example:
 
 ```sh
-npx cloud-run-functions dev ./path/to/functions/
+npx cloud-run-functions build functions
+npx functions-framework --target=build --source dist/index.js
 ```
 
-By default, any `.ts` or `.js` module is considered "loadable" by the dev server. This behavior is configurable with a `crf.config.json` file.
+### preview
 
-The dev server uses filesystem routing. By default, the dev server runs on port 8080. So if you do `http get :8080/hello` from your terminal, the dev server will look for a file called `hello.ts` or `hello.js` in the `./path/to/functions/` directory. If that file exists, its default export will be used as the function handler.
+Preview bundled functions locally.
 
-## Bundling
+```sh
+npx cloud-run-functions preview [--outDir <dir>]
+```
+
+- `--outDir, -o <dir>` sets the directory containing the bundled output. Default is `dist`
+
+This runs the Functions Framework using the `build` target and your bundled `index.js`.
+
+## Define values
 
-When you're ready to deploy, use the `build` command to bundle your functions.
+The CLI format is `--define key:value` or `-d key:value`.
+
+- If `value` looks like a number, it is used as one
+- Otherwise it is treated as a string literal
+
+Examples:
 
 ```sh
-npx cloud-run-functions build ./path/to/functions/
+npx cloud-run-functions dev functions -d process.env.STAGE:dev
+npx cloud-run-functions build functions -d __BUILD_ID__:123
 ```
 
-## Tips
+If you need full control over esbuild `define` values, use the programmatic API.
+
+## Configuration
+
+Create a `crf.config.json` file. \
+It is searched for by walking up from the `root` directory you pass to the CLI.
+
+Example:
+
+```json
+{
+  "root": "functions",
+  "entrySuffix": ".task",
+  "adapter": "node",
+  "maxInstanceConcurrency": 5
+}
+```
+
+Options:
+
+- `root` string. base directory when searching for entry points. default is the config directory
+- `globs` string array. globs to search within `root`. default is `["**/*"]`
+- `extensions` string array. file extensions to match. default is `[".ts", ".js"]`
+- `entrySuffix` string. require a suffix like `.task` before the extension
+- `adapter` `"node"` or `"hattip"`. default is `"node"`
+- `maxInstanceConcurrency` number or record of `{ [routeName]: number }`. default is `5`. used by `dev` to limit concurrent requests per route
+
+Adapter notes:
+
+- `adapter: "node"` means your default export should be a Functions Framework handler `(req, res) => ...`
+- `adapter: "hattip"` means your default export should be a Hattip app and it will be wrapped at runtime
+
+## Dotenv support
+
+If `dotenv` is installed, `dev` will load the closest `.env` file under your functions root.
+Values in `.env` do not override existing `process.env` values.
+
+## Programmatic API
+
+The package also exports the underlying functions used by the CLI:
+
+```ts
+import { build, dev, preview } from 'cloud-run-functions'
+```
 
-- If you have the [dotenv](https://www.npmjs.com/package/dotenv) package installed, the dev server will import it and automatically load environment variables from the closest `.env` file. Note that environment variables in `.env` won't override existing `process.env` values.
+See `src/index.ts` for the current exports and `src/tools/*.ts` for option types.