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";
import { edgeRuntime } from "@edgefirst-dev/core/hono";
import { Hono } from "hono";

import * as schema from "~/db/schema";

const app = new Hono<{ Bindings: Bindings }>();

// Add the edgeRuntime middleware
app.use(edgeRuntime({ orm: { schema } }));

export default app;

declare module "@edgefirst-dev/core" {
  // Extends @edgefirst-dev/core's Bindings with your bindings
  interface Bindings {}

  // Overwrite with the data you want to store in the session
  interface SessionData {
  }

  // Extends @edgefirst-dev/core's DatabaseSchema with the schema of your app
  interface DatabaseSchema {
    users: typeof schema.users;
  }
}

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";

[!WARNING] This function is memoized so the next time you call it, it will return the same instance of the env object.

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";

[!WARNING] This function is memoized so the next time you call it, it will return the same instance of the KV object.

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";

[!WARNING] This function is memoized so the next time you call it, it will return the same instance of the FS object.

[!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");

The fs().uploadHandler method is used to create a handler that can be used to upload files to the store.

import { parseFormData } from "@mjackson/form-data-parser";

let formData = await parseFormData(request, fs().uploadHandler(["avatar"]));

The uploadHandler method expects an array of keys that will be used to store the files. Optionally, a function can be provided to get the key from the file.

let formData = await parseFormData(
  request,
  fs().uploadHandler(["avatar"], (file) => {
    return `avatar:${file.name}`;
  })
);

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";

[!WARNING] This function is memoized so the next time you call it, it will return the same instance of the database.

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 orm function gives you access to a database object powered by Cloudflare D1 and Drizzle ORM.

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

[!WARN] This function is memoized, so the next time you call it, it will return the same instance of the Drizzle ORM, the memoization is not taking into account the arguments of the functions.

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.

[!WARNING] This function is memoized so the next time you call it, it will return the same instance of the cache object.

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 ai object gives you access to the AI services powered by Cloudflare AI.

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

[!WARNING] This function is memoized so the next time you call it, it will return the same instance of the AI object.

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

The 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 ai().textToImage(model, inputs, options);

The 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 ai().imageToText(model, inputs, options);

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

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

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

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

The 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 ai().textEmbeddings(model, inputs, options);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

let service = ai().binding;

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

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

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

[!WARNING] This function is memoized so the next time you call it, it will return the same instance of the queue object.

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

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

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

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

let queue = queue().binding;

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

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

import { 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 rateLimit object gives you access to the rate limiting object powered by Cloudflare Worker KV.

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

[!WARNING] This function is not memoized so the next time you call it, it will return a new instance of the rate limit object.

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

The rateLimit().limit method is used to limit the number of requests per key.

await rateLimit().limit({ key });

The rateLimit().reset method is used to reset the rate limit for a key.

await rateLimit().reset({ key });

The rateLimit().writeHttpMetadata method is used to write the rate limit metadata to the response headers.

await rateLimit().writeHttpMetadata({ key }, headers);

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.

Similarly, you can override the session data by creating a d.ts file in your project with this content

import "@edgefirst-dev/core";

declare module "@edgefirst-dev/core" {
  interface SessionData {
    // Add your custom session data here
  }
}

Similarly, you can override the session flash data by creating a d.ts file in your project with this content

import "@edgefirst-dev/core";

declare module "@edgefirst-dev/core" {
  interface SessionFlashData {
    // Add your custom session flash data here
  }
}

Similarly, you can override the database schema by creating a d.ts file in your project with this content

import "@edgefirst-dev/core";

import type * as schema from "~/db/schema"; // Your DB schema

declare module "@edgefirst-dev/core" {
  interface DatabaseSchema extends schema {}
}

• Sergio Xalambrí