The core of the Edge-first Stack.

bun add @edgefirst-dev/core

In your Hono server, add the edgeRuntime middleware

import type { Bindings } from "@edgefirst-dev/core"; // Binding types
import { edgeRuntime } from "@edgefirst-dev/core/hono"; // The middleware
import type { ServerBuild } from "@remix-run/cloudflare";
import { Hono } from "hono";
import { staticAssets } from "remix-hono/cloudflare";
import { remix } from "remix-hono/handler";

// Use the Bindings from `@edgefirst-dev/core` or extend it with your custom bindings
const app = new Hono<{ Bindings: Bindings }>();
app.use(staticAssets());

app.use(edgeRuntime()); //Add it before your Remix handler

app.use(async (c, next) => {
  let handler = remix({ build: await importServerBuild(), mode: "production" });
  return handler(c, next);
});

function importServerBuild(): Promise<ServerBuild> {
  if (process.env.NODE_ENV === "development" || import.meta.env.DEV) {
    // @ts-expect-error - TS doesn't know about virtual:remix/server-build
    return import("virtual:remix/server-build");
  }

  // @ts-expect-error - This file will not exists until we build the app
  return import("../build/server");
}

export default app;

Now you can import the functions from @edgefirst-dev/core and use it in any part of your Remix app.

The env function gives you access to the environment variables in a type-safe way.

import { env } from "@edgefirst-dev/core";

The env().fetch method is used to get a value from the environment variables.

The function expects the environment variable name. If the environment variable is not set and no fallback is provided, it will throw an EdgeEnvKeyError.

let CLIENT_ID = env().fetch("CLIENT_ID");

There's a second optional parameter that can be used as a fallback value if the environment variable is not set.

let SESSION_SECRET = env().fetch("SESSION_SECRET", "fallback");

The kv function gives you access to a Key-Value store powered by Cloudflare Worker KV.

import { kv } from "@edgefirst-dev/core";

The kv().keys method is used to get a list of keys in the store.

The function returns an object with the keys, a cursor to get the next page, and a boolean to know if there are more keys to fetch.

// Get a list of keys
let { keys, cursor, done } = await kv().keys();

In case done is true ther cursor will be null. Otherwise it will be a string that can be used to get the next page of keys.

let { keys, cursor, done } = await kv().keys({ cursor });

Additionally, a prefix can be provided to filter the keys.

let { keys, cursor, done } = await kv().keys("prefix", { cursor });

The kv().get method is used to get a single key from the store.

The function returns an object with the data and metadata of the key.

let { data, meta } = await kv().get("prefix:key");

The kv().set method is used to save a key in the store.

The function expects the key, the value, and an optional object with the TTL and metadata.

await kv().set("prefix:key", value, { ttl: 3600, metadata: { key: "value" } });

The kv().has method is used to check if a key is stored.

The function returns a boolean indicating if the key is stored.

let hasKey = await kv().has("prefix:key");

The kv().remove method is used to remove a key from the store.

await kv().remove("prefix:key");

A read-only property that gives you the KVNamespace used by the KV object.

let namespace = kv().binding;

[!TIP] The namespace can be used to access the KVNamespace directly in case you need to integrate with it.

The fs function gives you an instance of @mjackson/file-storage powered by Cloudflare R2.

import { fs } from "@edgefirst-dev/core";

[!TIP] Check @mjackson's File Storage documentation to know what's possible with this library. The FS#keys and FS#serve methods are not available in the original library, they are custom methods added by this library and therefore are documented here.

The fs().keys method is used to get a list of keys in the store.

let { keys, cursor, done } = await fs().keys();

The fs().serve method is used to get a response object that can be sent to the browser with the file data.

let response = await fs().serve("key");

A read-only property that gives you the R2Bucket used by the FS object.

let bucket = fs().binding;

[!TIP] The bucket can be used to access the R2 bucket directly in case you need to integrate with it.

The db function gives you access to a database object powered by Cloudflare D1.

import { db as edgeDb } from "@edgefirst-dev/core";

This object is compatible with D1 interface so it can be used with Drizzle ORM or any other D1 compatible library.

import { drizzle } from "drizzle-orm/d1";
import * as schema from "~/db/schema";

export const db = drizzle(edgeDb(), { schema });
export { schema };

A read-only property that gives you the D1Database used by the database object.

let database = db().binding;

[!TIP] The database can be used to access the D1 database directly in case you need to integrate with it.

The cache function gives you access to a cache object powered by Cloudflare Worker KV.

import { cache } from "@edgefirst-dev/core";

Every cached key will be prefixed by cache: to avoid conflicts with other keys.

The cache().fetch method is used to get a value from the cache or calculate it if it's not there.

The function expects the key, the TTL, and a function that will be called to calculate the value if it's not in the cache.

let ONE_HOUR_IN_SECONDS = 3600;

let value = await cache().fetch("key", ONE_HOUR_IN_SECONDS, async () => {
  // do something expensive and return the value
});

The TTL is optional, it defaults to 60 seconds if not provided.

await cache().fetch("another-key", async () => {
  // The TTL is optional, it defaults to 60 seconds
});

The cache().purge method is used to remove a key from the cache.

cache().purge("key");

A read-only property that gives you the KVNamespace used by the Cache object.

let namespace = cache().binding;

[!TIP] The namespace can be used to access the KVNamespace directly in case you need to integrate with it.

The request function gives you access to the current request object.

import { request } from "@edgefirst-dev/core";

let url = new URL(request().url);
request().headers.get("Authorization");

The headers function gives you access to the current request headers using @mjackson/headers.

[!TIP] Check @mjackson's Headers documentation to know what's possible with this library.

import { headers } from "@edgefirst-dev/core";

headers().cacheControl.maxAge;
// And other properties of the library

The signal function gives you access to the current request signal.

import { signal } from "@edgefirst-dev/core";
signal().aborted;

The unstable_ai object gives you access to the AI services powered by Cloudflare AI.

import { unstable_ai } from "@edgefirst-dev/core";

[!IMPORTANT] This marked as unstable because it's still in development and the API might change.

The unstable_ai().textToImage method is used to generates images from input text. These models can be used to generate and modify images based on text prompts

let output = await unstable_ai().textToImage(model, inputs, options);

The unstable_ai().imageToText method is used to output a text from a given image. Image captioning or optical character recognition can be considered as the most common applications of image to text

await unstable_ai().imageToText(model, inputs, options);

The unstable_ai().translation method is used to convert a sequence of text from one language to another.

await unstable_ai().translation(model, inputs, options);

The unstable_ai().summarization method is used to produce a shorter version of a document while preserving its important information.

await unstable_ai().summarization(model, inputs, options);

The unstable_ai().textEmbeddings method is used to transform raw data into numerical features that can be processed while preserving the information in the original dataset.

await unstable_ai().textEmbeddings(model, inputs, options);

The unstable_ai().textGeneration method is used to generate text based on a given prompt.

await unstable_ai().objectDetection(model, inputs, options);

await unstable_ai().speechRecognition(model, inputs, options);

await unstable_ai().textClassification(model, inputs, options);

await unstable_ai().imageClassification(model, inputs, options);

The unstable_ai().objectDetection method is used to detect instances of objects like persons, faces, license plates, or others in an image.

await unstable_ai().objectDetection(model, inputs, options);

The unstable_ai().speechRecognition method is used to convert a speech signal, typically an audio input, to text.

await unstable_ai().speechRecognition(model, inputs, options);

The unstable_ai().textClassification method is used to classify a text input into labels or classes.

await unstable_ai().textClassification(model, inputs, options);

The unstable_ai().imageClassification method is used to classify an image input into labels or classes.

await unstable_ai().imageClassification(model, inputs, options);

A read-only property that gives you the Cloudflare Ai object used by the AI object.

let service = unstable_ai().binding;

[!TIP] The service can be used to access the AIService directly in case you need to integrate with it.

The unstable_queue object gives you access to a Queue publisher powered by Cloudflare Queue.

import { unstable_queue } from "@edgefirst-dev/core";

[!IMPORTANT] This marked as unstable because it's still in development and the API might change.

The unstable_queue().enqueue method is used to enqueue a payload in the queue.

await unstable_queue().enqueue(payload, options);

A read-only property that gives you the Cloudflare Queue object used by the Queue object.

let queue = unstable_queue().binding;

[!TIP] The queue can be used to access the Queue directly in case you need to integrate with it.

The unstable_geo object gives you access to the geolocation data powered by Cloudflare CDN.

import { unstable_geo } from "@edgefirst-dev/core";

This function returns an object with the geolocation data. The object conforms to the interface:

interface Geo {
  country: Iso3166Alpha2Code | "T1";
  region: string;
  city: string;
  postalCode: string;
  latitude: string;
  longitude: string;
  timezone: string;
  metroCode: string;
  continent: ContinentCode;
  isEurope: boolean;
}

[!TIP] The Iso3166Alpha2Code and ContinentCode are union types provided by Cloudflare Worker types package.

The library may throw some errors, they can all be imported so you can handle them.

import {
  EdgeConfigError,
  EdgeContextError,
  EdgeEnvKeyError,
  EdgeRequestGeoError,
} from "@edgefirst-dev/core";

You can override the bindings by creating a d.ts file in your project with this content

import "@edgefirst-dev/core";

declare module "@edgefirst-dev/core" {
  interface Bindings {
    // Add your custom bindings here
  }
}

If you're using wrangler types to generate the types, you can make Bindings extends the interface generated by wrangler types.

• Sergio Xalambrí