This is my mental model of databases, which I learned during an internship interview and has stuck with me through 5+ years of working professionally on data loading platforms.

- Databases are just big spreadsheets
- An index is just a view of the spreadsheet sorted by one or more columns
- Binary search[^1] over a sorted list is faster than a linear scan (for large lists)

Imagine storing movies in a spreadsheet. It might look something like this:
![A picture of a spreadsheet of movies sorted by ID.](https://cdn.sanity.io/images/ts10onj4/production/01b3ed095be6ed9dfe0d5be1f5c698b599bea72d-2346x903.jpg)

We want to store this with *some* order, so this spreadsheet is sorted by the first column -- a unique `_id` field.[^2] This means we can quickly find a document from this table given its ID because we can binary search.

Let’s say we want to build a way for users to see all the movies for a given director like this (here, sorted by release date):
![A picture of the Letterboxd UI](https://cdn.sanity.io/images/ts10onj4/production/418999fc35be9194c215132ce46335eff2331dfd-1456x892.png)

We might want a view that sorts by the director, and then the year:
![A spreadsheet tab sorted by director, and then year](https://cdn.sanity.io/images/ts10onj4/production/85805fd844f6719a9069d2f00d1c521b35cd5b83-1697x1053.jpg)
![Spreadsheet tabs with Movies.ByDirectorAndYear selected](https://cdn.sanity.io/images/ts10onj4/production/88f25e7a749cdd0be8ee8ea631724389061662a2-1734x126.jpg)

This is an index! We could define it with convex like so:

```ts
Movies: defineTable(...).index("ByDirectorAndYear", ["director", "year"])
```

This is like another tab in our spreadsheet, and we use the `_id` to reference the document in the first tab to avoid needing to include the full document in each tab of the spreadsheet (the movie names are shown to the side for convenience). 

We can use it to make the following query:


**Goal**: Get all movies directed by Nolan.


**Code**: `db.query(”Movies”).withIndex(”ByDirectorAndYear”, q => q.eq("director", "Nolan")) `


**Picture:**
![Selecting the block of Nolan movies from the ByDirectorAndYear tab](https://cdn.sanity.io/images/ts10onj4/production/b164c267bedfab729386e434be5968c8f496f8e4-1745x1051.jpg)

We use the `Movies.ByDirectorAndYear` tab to binary search for the first entry with “Nolan”, and keep grabbing rows until we reach a new director. Once we have all these IDs, we can grab the full documents from the first table `Movies.ById`, binary searching for each ID. This means we can efficiently grab any contiguous chunk from our spreadsheet. 

One thing we can observe right away is that when a new movie gets added or updated in the first tab, we also need to add an entry to each tab in our spreadsheet. This means each index has a bit of write overhead and also requires some additional storage.

But the `Movies.ByDirectorAndYear` tab is useful for making fast queries that take advantage of the sorted order in that tab, so if we're making a lot of queries that use this ordering, the write overhead + additional storage for maintaining this extra tab is worth it.


We can use this mental model to go through a few more queries and make some observations:

### We must go through columns in index order

**Goal:** Get all movies from 2023.

**Code:** ❌ `db.query(”Movies”).withIndex(”ByDirectorAndYear”, q => q.eq("year", 2023))`

**Picture:**
![Demonstrating that movies made in 2023 are not contiguous in the ByDirectorAndYear index](https://cdn.sanity.io/images/ts10onj4/production/201603f90607110a31dca191d79af26c6f81c1c3-1724x1048.jpg)

This query does not select a contiguous chunk from the spreadsheet — to find all the movies from 2023, we’d have to look at every single row and can’t use the sorted columns in this tab to our advantage.

### Inequalities
Now let’s consider a new index `ByYearAndDirector` (which would be a better choice for the example above).

**Goal:** Get all movies created in 2018 or later.


**Code:** ✅ `db.query(”Movies”).withIndex(”ByYearAndDirector”, q => q.gte("year", 2018))`


**Picture:**
![Movies sorted by year and then by director](https://cdn.sanity.io/images/ts10onj4/production/ec1af4d30d37034e0e49ec998bcb076950f71046-1759x1052.jpg)
![Spreadsheet tabs showing ByYearAndDirector selected](https://cdn.sanity.io/images/ts10onj4/production/7e8d3b5af39317dc4870b800b0a1513da35abbf1-2546x132.jpg)

Even though this isn’t an “equals”, we can still binary search and select a contiguous block with “greater than” or “less than”.

…But we can only use “greater than” at the end.

**Goal:** Get all movies created in in 2000 or later with directed by Nolan.


**Code:** ❌ `db.query(”Movies”).withIndex(”ByYearAndDirector”, q => q.gte("year", 2000).eq("director", "Nolan")`


**Picture**:
![Demonstrating a query with an inequality filter followed by an equality field](https://cdn.sanity.io/images/ts10onj4/production/2ce7930e66e178c04909f57c9514e6625128e6a0-1805x899.jpg)

We can’t do “not equals” in a single efficient query — we need to do two binary searches.

**Goal:** Get all movies not made in 2018.


**Code:** 


❌ `db.query(”Movies”).withIndex(”ByYearAndDirector”, q => q.neq("year", 2018))`



✅ `db.query(”Movies”).withIndex(”ByYearAndDirector”, q => q.gt("year", 2018))` and `db.query(”Movies”).withIndex(”ByYearAndDirector”, q => q.lt("year", 2018))`

**Picture**:
![Demonstrating a "not equals" query is actually two separate queries](https://cdn.sanity.io/images/ts10onj4/production/9e77e0fa28d5636879f809d3fa711b8e2fe7cb00-1795x907.jpg)

### No efficient “in” / “or”
**Goal:** Get movies directed by Nolan or Gerwig.


**Code:** 


❌ `db.query(”Movies”).withIndex(”ByDirectorAndYear”, q => q.in("director", ["Nolan", "Gerwig"]))`


✅  `db.query(”Movies”).withIndex(”ByDirectorAndYear”, q => q.eq("director", "Nolan"))` and `db.query(”Movies”).withIndex(”ByDirectorAndYear”, q => q.eq("director", "Gerwig"))`

**Picture:**
![Demonstrating an "in" query is really N separate queries](https://cdn.sanity.io/images/ts10onj4/production/d6ce8a9acc04b3dd7ff50d809698d94b45ccfa01-1816x1048.jpg)

This is really a separate query for each element in the “in” / “or” expression and cannot be done in a single efficient query.

## Convex’s query syntax

Convex's syntax aims to make it clear what's efficient vs. what's not. Things in `withIndex` will be more efficient binary searches, things in `filter` or in plain JavaScript are not. 

Going through the examples above:

- We prevent `.withIndex("ByDirectorAndYear", q => q.eq("year", 2023))` (skipping fields)
- We prevent `.withIndex("ByYearAndDirector"), q => q.gte("year", 0).eq("director", "Gerwig")` (non-final inequalities)
- There's no `or`, `in`, `neq` for `withIndex`

In comparison, it’s easy to write all of these as a SQL query without realizing they’re slow. Just because it is possible to write a query in SQL doesn't mean it'll be fast -- SQL's query planner will just try its best to choose from the indexes you have and do a linear scan of the table if there's no better option.

Something like `SELECT * from Movies WHERE title = "Barbie" LIMIT 1` might look innocent enough, but if there's no index on `title`, the query planner will iterate over the entire table. Even knowing all the indexes on a table, it’s often hard to tell whether a SQL query is efficient or not by looking at it since it's difficult to predict exactly what the query planner will choose to do.

## Why should I choose my indexes?

Now we have a mental model of how indexes and databases work, but you might be asking why it’s valuable to think about this or why *you* should be the one deciding exactly which indexes you want.

If we keep applying the “databases are spreadsheets” mental model to different queries and indexes, we’ll find that some indexes aren’t actually that useful ...and it's usually specific to the product you're designing.

As an example, most directors only have a few movies (&lt;20). Once we've narrowed down to the movies for a single director, binary searching within those ~20 for movies in a certain year or with a certain rating isn’t much more efficient than scanning all of them. Instead of a `ByDirectorAndYear` index, we might just want `ByDirector`, and do any sorting and filtering we want without an index (in JavaScript):

```typescript
const nolanMovies = await db.query("Movies")
	.withIndex("ByDirector", q => q.eq("director", "Nolan"))
	.collect();
// sort by release date
nolanMovies.sort((a, b) => a.year - b.year))
```

If we wanted to allow a bunch of different sorts and filters for a single director’s movies, we probably can just do all the sorting and filtering in JavaScript and don’t need an index. (e.g. “Get movies directed by Nolan sorted by title”, “Get movies directed by Nolan available on Hulu”).

On the other hand, we might want a `ByGenreAndYear` or a `ByGenreAndRating` index, since there are many movies in a genre, so it’s useful to be able to efficiently narrow down the results further (e.g. “Get the top 50 rated horror movies”, “Get comedy movies released in the last 5 years”). We might even design our product to have fewer sorts and filters for the genre pages than for the director pages to avoid needing a bunch of indexes.

As another example, an index like `ByTitle` also might not be that useful. Your users probably won’t want a list of all movies ever listed alphabetically and probably won’t look up a movie with the exact title. Instead you might want a full text search index[^3] on the title (so users can type “the dark kni” to find a movie), or you might want an index like `ByTitleSlug` where each movie has a unique slug (e.g. `little-women`, `little-women-2019`) that can be used in URLs.

# Summary

To repeat the mental model:
- Databases are just big spreadsheets
- An index is just a view of the spreadsheet sorted by one or more columns
- Binary search over a sorted list is faster than a linear scan (for large lists)


Database indexes can be thought of as separate spreadsheet tabs that we keep in a specific sorted order, and keep up to date on every addition or update to the original data. Indexes are useful for making queries fast as long as we can select a contiguous chunk from the spreadsheet tab, using binary search instead of scanning the entire spreadsheet.

Hopefully thinking of databases as spreadsheets is helpful for thinking about when and how to define an index based on the data you’re storing and the product you’re building. Convex is designed to make performance of queries clear by only supporting the operations that can be done efficiently in our query syntax.



[^1]: This is actually a B-Tree look up in a real database since they're designed to work efficiently with hard drives, but the mental model of binary search is pretty similar (O(log n) search on a sorted list).
[^2]: This is called the "primary key" in databases.
[^3]: How search indexes work probably merits an entirely separate post, but they're similar to the "spreadsheet tab" mental model in the sense that they require extra storage + write overhead, and that the parts of the query in `withSearchIndex` will be efficient compared to `filter` or plain JavaScript.


I want to share my mental model of databases:

- Databases are just big spreadsheets
- An index is just a view of the spreadsheet sorted by one or more columns
- Binary search over a sorted list is faster than a linear scan (for large lists)

Databases are Spreadsheets

**Note:** This article was written before we released the [`convex-test`](https://www.npmjs.com/package/convex-test) library along with the [testing guidance](https://docs.convex.dev/functions/testing) to use it for unit tests. We generally recommend writing unit tests using `convex-test` over using a local backend, and [this section](https://docs.convex.dev/functions/testing#testing-using-the-local-backend) lists some of the pros and cons for testing against a local backend.

Convex recently released an [open source version](https://github.com/get-convex/convex-backend) of the backend. We can use this to unit test Convex functions by running them with a local backend. These tests will work by running a backend locally, pushing your code, and using the `ConvexClient` to execute queries and mutations from your favorite testing framework and asserting on the results.

Here’s an [example](https://github.com/get-convex/convex-helpers/blob/main/convex/example.test.ts) of a simple test we might want to write if we were building a notes app:
```ts
  test("can only read own notes", async () => {
    const personASessionId = "Person A";
    await t.mutation(api.notes.add, {
      sessionId: personASessionId,
      note: "Hello from Person A"
    });

    await t.mutation(api.notes.add, {
      sessionId: personASessionId,
      note: "Hello again from Person A"
    });

    const personBSessionId = "Person B";
    await t.mutation(api.notes.add, {
      sessionId: personBSessionId,
      note: "Hello from Person B"
    });

    const personANotes = await t.query(api.notes.list, {
      sessionId: personASessionId
    });
    expect(personANotes.length).toEqual(2);
  });
	```
	
# 	Setting up a local backend
First, we need to make sure we are able to run a local backend by following the instructions [here](https://github.com/get-convex/convex-backend?tab=readme-ov-file#getting-started). Make sure `just run-local-backend` runs successfully.

To make it easier to interact with the local backend from our project, we can add a [`Justfile`](https://github.com/get-convex/convex-helpers/blob/main/Justfile) supporting the following commands: `just run-local-backend`, `just reset-local-backend`, and `just convex [args]` to run Convex CLI commands against the local backend. These can be copied from the open source backend's [`Justfile`](https://github.com/get-convex/convex-backend/blob/main/Justfile).

We want a command like `npm run testFunctions` that does the following:

- Ensures a fresh local backend is running
- Sets the `IS_TEST` environment variable, allowing us to run testing only functions (`just convex env set IS_TEST true`)
- Pushes code to the local backend (`just convex deploy`)
- Runs the tests (e.g. `npx vitest`)
- Finally, tears down the local backend

One way to do this is to write a script, [`backendHarness.js`](https://github.com/get-convex/convex-helpers/blob/main/backendHarness.js), that handles setting up the local backend, runs a command, and finally tears down the backend.

We can add commands to our [`package.json`](https://github.com/get-convex/convex-helpers/blob/main/package.json) that look something like this:
```json
// package.json
"scripts": {
	// Test assuming there's an existing local backend running
	"testFunctionsExistingBackend": "just convex env set IS_TEST true && just convex deploy && vitest",
	// Test handling local backend creation + cleanup
	"testFunctions": "node backendHarness.js 'npm run testFunctionsExistingBackend'"
}
```

# Writing tests
In this set up, all our tests will be running against the same local backend, since running a backend for each test would be too slow. To keep tests isolated from each other, we want to configure our testing framework to run tests one at a time (e.g. `maxWorkers: 1` in [vitest.config.mts](https://github.com/get-convex/convex-helpers/blob/main/vite.config.mts)) and also call a function to clear out all our data after each test.

We’ll add a [clearAll mutation](https://github.com/get-convex/convex-helpers/blob/main/convex/testingFunctions.ts#:~:text=clearAll) that looks something like this:
```ts
export const clearAll = testingMutation(async (ctx) => {
  for (const table of Object.keys(schema.tables)) {
    const docs = await ctx.db.query(table as any).collect();
    await Promise.all(docs.map((doc) => ctx.db.delete(doc._id)));
  }
  const scheduled = await ctx.db.system.query("_scheduled_functions").collect();
  await Promise.all(scheduled.map((s) => ctx.scheduler.cancel(s._id)));
  const storedFiles = await ctx.db.system.query("_storage").collect();
  await Promise.all(storedFiles.map((s) => ctx.storage.delete(s._id)));
})
```
It clears data from all tables listed in the schema, cancels any scheduled jobs, and deletes any stored files. 

The [`testingMutation` wrapper](https://github.com/get-convex/convex-helpers/blob/main/convex/testingFunctions.ts#:~:text=testingMutation) uses [`customMutation`](https://github.com/get-convex/convex-helpers/blob/main/packages/convex-helpers/server/customFunctions.ts) from `convex-helpers` to ensure all functions check that the `IS_TEST` environment variable is set to prevent `clearAll` from being called on Production or Development deployments.

```ts
export const testingMutation = customMutation(mutation, {
  args: {},
  input: async (_ctx, _args) => {
    if (process.env.IS_TEST === undefined) {
      throw new Error(
        "Calling a test only function in an unexpected environment"
      );
    }
    return { ctx: {}, args: {} };
  },
});
```

Putting all of this together, we can write a [test](https://github.com/get-convex/convex-helpers/blob/main/convex/example.test.ts) for our Convex functions which we can run via `npm run testFunctions`:
```ts
import { api } from "./_generated/api";
import { ConvexTestingHelper } from "convex-helpers/testing";

describe("testingExample", () => {
  let t: ConvexTestingHelper;

  beforeEach(() => {
    t = new ConvexTestingHelper();
  });

  afterEach(async () => {
    await t.mutation(api.testingFunctions.clearAll, {});
    await t.close();
  });

  test("can only read own notes", async () => {
    const personASessionId = "Person A";
    await t.mutation(api.notes.add, {
      sessionId: personASessionId,
      note: "Hello from Person A"
    });

    await t.mutation(api.notes.add, {
      sessionId: personASessionId,
      note: "Hello again from Person A"
    });

    const personBSessionId = "Person B";
    await t.mutation(api.notes.add, {
      sessionId: personBSessionId,
      note: "Hello from Person B"
    });

    const personANotes = await t.query(api.notes.list, {
      sessionId: personASessionId
    });
    expect(personANotes.length).toEqual(2);
  });
});
```

A PR setting up tests for a Chess app built on Convex, following this guide, can be found [here](https://github.com/get-convex/convex-chess/pull/19). It includes some examples of [more complex tests](https://github.com/get-convex/convex-chess/blob/main/games.test.ts).

It includes testing authenticated functions (this uses the same mechanism as the dashboard function tester to act as a particular user)
```ts
 const sarahIdentity = t.newIdentity({ name: "Sarah" });
 const asSarah = t.withIdentity(sarahIdentity);
 
 const gameId = await asSarah.mutation(api.games.newGame, {
	 player1: "Me",
	 player2: null,
 });
 let game = await t.query(api.games.get, { id: gameId });
 expect(game.player1Name).toEqual("Sarah");
```

It also uses test only mutations to set up data (setting up a chess game 2 moves from the end):
```ts
// Two moves before the end of the game
const gameAlmostFinishedPgn = "1. Nf3 Nf6 2. d4 Nc6 3. e4 Nxe4" /* ... */

const gameId = await t.mutation(api.testing.setupGame, {
	player1: sarahId,
	player2: leeId,
	pgn: gameAlmostFinishedPgn,
	finished: false,
});
```

# Limitations

Scheduled functions (`ctx.scheduler` and crons) will run in this local backend as time progresses, and while it’s possible to check the state of a scheduled job using [`ctx.db.system`](https://docs.convex.dev/database/advanced/system-tables), there’s no built in way to run a scheduled function for testing or to mock out time and manually advance it in tests.

There is also no built in way to mock out or control randomness in the tested functions.

See the [documentation](https://docs.convex.dev/functions/testing#testing-using-the-local-backend) for a comparison of this testing strategy with unit tests using the [`convex-test`](https://www.npmjs.com/package/convex-test) library.

# Summary

Convex functions can be unit tested using a locally running Convex backend.

Check out [the open source backend](https://github.com/get-convex/convex-backend) or see [an example](https://github.com/get-convex/convex-chess/pull/19) of these tests in action!

Convex recently released an open source version of the backend. We can use this to unit test Convex functions by running them with a local backend. These tests will work by running a backend locally, pushing your code, and using the `ConvexClient` to execute queries and mutations from your favorite testing framework and asserting on the results.

Running tests using a local open-source backend

[Convex](https://convex.dev) supports [HTTP actions](https://docs.convex.dev/functions/http-actions), meaning your backend can receive requests not only from Convex clients, such as the [ConvexReactClient](https://docs.convex.dev/using/project-setup#configure-the-convex-client), but also from third-party webhooks and other clients that want to communicate with a custom HTTP API. 

Currently, these endpoints have a simple router. In this post, we’ll look at how to add more advanced features, such as:

- Dynamic routes or slug routes — e.g. `users/:userId`
- Middleware — e.g. check auth on all routes under `/api/*` or implementing CORS
- Helpers for validating an incoming Request’s query params or body
- Helpers for formatting a JSON response or text response
- Custom 404 (Not Found) responses

While it’s possible to build these yourself on top of Convex primitives, existing JS libraries already do a great job at this. In this post, we’re going to go through how you can leverage [Hono](https://hono.dev/) with Convex [HTTP actions](https://docs.convex.dev/functions/http-actions). To see the implementation, check out  [`hono.ts`](https://github.com/get-convex/convex-helpers/blob/main/packages/convex-helpers/server/hono.ts) in the [convex-helpers package](https://www.npmjs.com/package/convex-helpers#hono-for-advanced-http-endpoint-definitions). We’ll also look more generally at how to extend Convex HTTP endpoint behavior. 

Note: you don’t need to use TypeScript, but I will use it in my examples because both Hono and Convex offer slick TypeScript support! 

# Using Hono with Convex

To use Hono, you’ll need to:

1. `npm install hono convex-helpers` in your project. 
2. In `convex/http.ts`, import `Hono`, `HonoWithConvex`, `HttpRouterWithHono`, and `ActionCtx`[^1]:

[^1]: `HonoWithConvex` and `ActionCtx` are just being used for types. If you're using JavaScript, you can ignore that import and just initialize `app` as `const app = new Hono();`

```ts
import { Hono } from "hono";
import { HonoWithConvex, HttpRouterWithHono } from "convex-helpers/server/hono";
import { ActionCtx } from "./_generated/server";

const app: HonoWithConvex<ActionCtx> = new Hono();

// Add your routes to `app`. See below 

export default new HttpRouterWithHono(app);
```

The `HonoWithConvex` is just a type that tells Hono to expect the Convex [`ActionCtx`](https://docs.convex.dev/generated-api/server#actionctx) as its [env](https://hono.dev/api/context#env) binding. `HttpRouterWithHono` does the magic to connect Hono routes to Convex HTTP actions.

Let’s look at a few ways to use Hono:

## Slug routing and response formatting

For illustration, we’ll implement an endpoint from the [Convex demo for HTTP action](https://github.com/get-convex/convex-demos/tree/main/http) to use Hono. Here’s an example handler showcasing several of Hono’s features:

```ts
// Routing with slugs
app.get("/listMessages/:userId{[0-9]+}", async (c) => {
  // Extracting a token from the URL!
  const userId = c.req.param("userId");

  // Running a Convex query
  const messages = await c.env.runQuery(api.messages.getByAuthor, { authorNumber: userId });

  // Helpers for pretty JSON!
  c.pretty(true, 2);
  return c.json(messages);
});
```

…and an example response:

```bash
$ curl https://happy-animal-123.convex.site/listMessages/123
[
  {
    "_creationTime": 1677798437141.091,
    "_id": {
      "$id": "messages|lqMHm5kDS9m6fBsSnx5L2g"
    },
    "author": "User 123",
    "body": "Hello world"
  },
]
```

## Input validation

Here’s another handler with input validation:

```typescript
import { z } from "zod";
import { zValidator } from "@hono/zod-validator";

app.post(
  "/postMessage",
  // Body validation!
  zValidator(
    "json",
    z.object({
      author: z.string().startsWith("User "),
      body: z.string().max(100),
    })
  ),
  async (c) => {
    // With type safety!
    const { body, author } = c.req.valid("json");
    await c.env.runMutation(api.messages.send, { body, author });
    return c.text("Sent message!");
  }
);
```

…and an example response:

```bash
$ curl -d '{ "body": "Hello world", "author": "123" }'  https://happy-animal-123.convex.site/postMessage
{
  "success": false,
  "error": {
    "issues": [
      {
        "code": "invalid_string",
        "validation": {
          "startsWith": "User "
        },
        "message": "Invalid input: must start with \"User \"",
        "path": [
          "author"
        ]
      }
    ],
    "name": "ZodError"
  }
}
```

## Middleware: Adding CORS

Another example, copying from [Hono docs](https://hono.dev/middleware/builtin/cors). This adds CORS support to the `/api/*` and `/api2/*` routes with different configurations.

```typescript
import { cors } from 'hono/cors'
...
app.use('/api/*', cors())

app.use(
  '/api2/*',
  cors({
    origin: 'http://examplesite.com',
    allowHeaders: ['X-Custom-Header', 'Upgrade-Insecure-Requests'],
    allowMethods: ['POST', 'GET', 'OPTIONS'],
    exposeHeaders: ['Content-Length', 'X-Kuma-Revision'],
    maxAge: 600,
    credentials: true,
  })
)
```

The `.use` function registers a handler for all `/api/*` requests. As we’ll see below, you can use this for a variety of situations, including logging.

## Custom 404 responses

To set up a custom 404, we can do:

```typescript
// Custom 404
app.notFound(c => {
  return c.text("Oh no! Couldn't find a route for that", 404);
});
```

See [https://hono.dev/](https://hono.dev/) for more features.

<BuildWithConvex />

# Under the hood

Curious about how to extend Convex [HTTP actions](https://docs.convex.dev/functions/http-actions) for your own purposes? Read on!

## Extending routes using the `/` prefix

If the routing options aren’t flexible enough for your use case, you can handle all HTTP requests with a single `httpAction` and do complex routing there. For instance, instead of using `HttpRouterWithHono`, we could define a single route per HTTP method in `convex/http.ts`:

```typescript
import { httpRouter, ROUTABLE_HTTP_METHODS } from "convex/server";
import { httpAction } from "./_generated/server";
import { HonoWithConvex } from "./lib/honoWithConvex";

const app: HonoWithConvex = new Hono();

// Add your routes to `app`.

const http = httpRouter();
for (const routableMethod of ROUTABLE_HTTP_METHODS) {
	http.route({
		pathPrefix: "/",
		method: routableMethod,
		handler: httpAction(async (ctx, request: Request) => {
			return await app.fetch(request, ctx);
		}),
	})
}
export default http;
```

We could stop here — we can now use Hono and Convex together! But we could make a couple of additional improvements to leverage the [Convex dashboard](https://dashboard.convex.dev/).

## Using middleware to add per-route logging

Here’s what we see in the [Convex dashboard](https://dashboard.convex.dev/) under “Logs” given the approach of registering an `httpAction` per method:

![Logs showing GET /*](https://cdn.sanity.io/images/ts10onj4/production/06c3e0c48a26da60a29a095e5c6f5e184d6ae2b0-1302x310.png?w=700)

All our GET requests will appear as `GET /*` even when we have multiple routes.

We can pretty easily get a little more information using one of Hono’s features — logging middleware:

```typescript
import { logger } from "hono/logger";
import stripAnsi from "strip-ansi";

app.use(
  "*",
  logger((...args) => {
    console.log(...args.map(stripAnsi));
  })
);
```

Now the [Convex dashboard](https://dashboard.convex.dev/) looks more like this:

![Logs with GET /listMessages/123](https://cdn.sanity.io/images/ts10onj4/production/e1ff98ab9fdcc7e5eee3b741eca5025b98c762e9-1350x524.png?w=700)

Note: these say `0ms` because they’re running in [Convex’s deterministic environment that provides a different `Date.now()`](https://docs.convex.dev/understanding/convex-fundamentals/functions#determinism).

## Subclassing `HttpRouter` (the `HttpRouterWithHono` approach)

If we want the fullest integration with the [Convex dashboard](https://dashboard.convex.dev/), we’d like to see something like this under “Logs”, where we show the routed path:

![Logs showing GET /listMessages/:userId](https://cdn.sanity.io/images/ts10onj4/production/212100c96760c3d1b86ec79a59ce3d5246a60ca3-1526x514.png?w=700)

And then see a corresponding entry with metrics under the “Functions” tab:

![Functions metrics for GET /listMesssages/:userId](https://cdn.sanity.io/images/ts10onj4/production/9527a4a514b8fb6aa98023e27da58b90fbdede3b-970x922.png?w=450)

The code needed for this behavior is in  [`honoWithConvex.ts`](https://github.com/get-convex/convex-helpers/blob/main/convex/lib/honoWithConvex.ts).

**How does it work?**

`HttpRouterWithHono` is a subclass of the Convex [`HttpRouter`](https://docs.convex.dev/api/classes/server.HttpRouter) which overrides two special methods:

- `getRoutes` returns a list of `[path, method, handler]`, which we use to populate the Functions page on the dashboard.
- `lookup(path, method)` returns `[handler, path, method]`. Convex will run `handler` when responding to the request and use the `path` and `method` for metrics and logging (so this should match a path + method combo from `getRoutes`)
    - As an example, I wanted `lookup("/listMessages/123", "GET")` to return `"/listMessages/:userId{[0-9]+}"` for the path and `"GET"` for the method.

The implementation I added is not optimal (it loops through all the routes), but it still works! The Convex router is very flexible, so there are many options for configuring how your HTTP actions get routed and show up in the dashboard. 

Now, we can use Convex with Hono and take advantage of most of the features provided in the Convex dashboard!

# Summary

In this post, we looked at how to use Hono with Convex, including how to extend Convex’s HTTP actions to add your own functionality. Let us know what you think in [our discord](https://convex.dev/community) and if you end up using Hono and Convex together! ❤️

Adding advanced HTTP Endpoint functionality by extending Convex with Hono.

Sarah Shader

All posts by Sarah