cloud-run-functions 0.2.0 → 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-NINUPPZA.js → chunk-L3GFRAQX.js}

@@ -65,6 +65,7 @@ async function build(root, { define, outdir } = {}) {
     logOverride: {
       "empty-glob": "silent"
     },
+    external: ["@google-cloud/functions-framework"],
     plugins: [
       {
         name: "crf-virtual-functions",
@@ -76,18 +77,20 @@ async function build(root, { define, outdir } = {}) {
             path: virtualModuleId,
             namespace: virtualModuleNamespace
           }));
-          build2.onLoad({ filter: /.*/, namespace: virtualModuleNamespace }, () => ({
-            contents: createVirtualModule({
-              routes,
-              adapter
-            }),
-            loader: "js",
-            resolveDir: functionsRoot
-          }));
+          build2.onLoad(
+            { filter: /.*/, namespace: virtualModuleNamespace },
+            () => ({
+              contents: createVirtualModule({
+                routes,
+                adapter
+              }),
+              loader: "js",
+              resolveDir: functionsRoot
+            })
+          );
         }
       }
-    ],
-    external: adapter === "hattip" ? [] : ["@hattip/adapter-node"]
+    ]
   });
   console.log(
     `[esbuild] Bundled ${routes.length} function${routes.length === 1 ? "" : "s"} into ${outfile}`

package/dist/{chunk-PFVLROGP.js → chunk-XHFBJ7D2.js}

@@ -10,18 +10,14 @@ function preview({ outDir, ...options } = {}) {
   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}`
-      }
+  return $("functions-framework --target=build --source %s", [source], {
+    stdio: "inherit",
+    ...options,
+    env: {
+      ...options.env ?? process.env,
+      PATH: `${binDir}:${process.env.PATH}`
     }
-  );
+  });
 }
 
 export {

package/dist/index.js

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

package/dist/tools/build.d.ts

@@ -36,11 +36,11 @@ declare function build(root?: string, { define, outdir }?: BundleOptions): Promi
     logOverride: {
         'empty-glob': "silent";
     };
+    external: string[];
     plugins: {
         name: string;
         setup(build: esbuild.PluginBuild): void;
     }[];
-    external: string[];
 }>>;
 
 export { type BuildOptions, type BundleOptions, build };

package/dist/tools/build.js

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

package/dist/tools/preview.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cloud-run-functions",
   "type": "module",
-  "version": "0.2.0",
+  "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.