DEV Community: Allen Jones

JavaScript and TypeScript Interview Questions Explained With Real Production Examples

Allen Jones — Thu, 10 Sep 2026 01:20:07 +0000

Most explanations of these concepts stop at the definition. Scope gets a rule about hoisting. Closures get a counter function that increments a number nobody would ever ship. The event loop gets a diagram. any versus unknown gets a one-line rule. Generics get a toy example with numbers and strings that never shows up in a real codebase.

That's enough to answer a question in an interview. It's not enough to actually recognize these patterns when they show up in your own code, which is the thing that matters once you're past the interview and actually shipping something.

This is the first in a short series working through concepts that come up constantly in interviews, explained the way I'd actually explain them to someone on my team, with real examples from production code, not just the textbook version.

var, let, and const

var, let, and const are the three ways to declare a variable in JavaScript. var is function-scoped and can be redeclared and reassigned freely. let is block-scoped and can be reassigned but not redeclared in the same scope. const is block-scoped and can't be reassigned after its initial value is set, though an object or array it points to can still be mutated internally.

The rule everyone learns is "use const by default, let when a value changes, avoid var." The part that's harder to see from that rule alone is what it looks like once real state is involved, not just a single reassignment.

Take pagination on a leads or submissions list, the kind of thing Formgrid.dev's dashboard actually does:

const pageSize = 20;
let currentPage = 1;

function nextPage() {
  currentPage++;
}

pageSize never changes for the life of that list, so const says so directly. currentPage changes every time someone clicks through the pagination, so let is the honest choice. The value of picking correctly here isn't stylistic; it's that anyone reading this code later can tell, without tracing every line, which values are safe to assume are fixed and which ones move. var doesn't offer that signal at all, and it doesn't respect block scope the way let and const do, which is reason enough to leave it out of new code entirely.

Closures

A closure is a function that keeps access to variables from the scope it was created in, even after that outer scope has already finished running.

The clearest real-world use of a closure is a small API client factory:

function createApiClient(baseUrl: string) {
  return {
    get(endpoint: string) {
      return fetch(`${baseUrl}${endpoint}`);
    },
    post(endpoint: string, data: unknown) {
      return fetch(`${baseUrl}${endpoint}`, {
        method: "POST",
        body: JSON.stringify(data),
      });
    },
  };
}

const api = createApiClient("https://api.example.com");

api.get("/users");
api.get("/products");

createApiClient() finishes running the moment it returns, but the object it hands back still remembers baseUrl. That's the closure: get and post keep access to a variable from a scope that's technically already finished executing.

The reason this matters beyond the definition is what it lets you do: create multiple independent clients from the same function, each remembering its own configuration.

const productionApi = createApiClient("https://api.example.com");
const stagingApi = createApiClient("https://staging.example.com");

Each one is a separate closure over a different baseUrl, with zero shared state between them. This is the same shape I'd reach for anywhere a function needs to remember configuration without a class: event handlers, callbacks, factories, or anything that needs private state without exposing it directly.

Promise.all, when requests don't depend on each other

Promise.all() takes an array of promises and resolves once every one of them has resolved, returning their results in the same order. If any single promise in the array rejects, Promise.all() rejects immediately, discarding the results of everything else.

Formgrid's dashboard loads several independent things on page load: lead pipeline stats, recent submissions, integration status, and account usage. None of them depend on each other's results.

The naive version waits for each one in sequence:

const stats = await fetchPipelineStats();
const submissions = await fetchRecentSubmissions();
const integrations = await fetchIntegrationStatus();
const usage = await fetchAccountUsage();

If each of those takes something like 500ms, 800ms, 600ms, and 300ms, waiting for them one at a time adds up to roughly 2.2 seconds before the dashboard can render anything.

const [stats, submissions, integrations, usage] = await Promise.all([
  fetchPipelineStats(),
  fetchRecentSubmissions(),
  fetchIntegrationStatus(),
  fetchAccountUsage(),
]);

Run concurrently instead; the total time is close to the slowest single request, around 800ms, not the sum of all four. Promise.all is the right tool specifically when the requests are genuinely independent, and you need all of them to proceed.

Promise.allSettled, when one failure shouldn't take down the rest

Promise.allSettled() also takes an array of promises, but it waits for every one of them to finish regardless of outcome, and returns an array describing each result as either fulfilled, with its value, or rejected, with its reason. Nothing gets discarded because one promise failed.

The catch with Promise.all is that a single rejection fails the entire batch. That's fine when every result is required before anything can render. It's the wrong choice when one piece failing shouldn't block the others.

Say the AI Smart Inbox category breakdown widget on that same dashboard has a bad moment and its request fails, while the lead stats, submissions, and integrations requests all succeed fine. With Promise.all, that one failure would throw away three perfectly good results along with it.

const results = await Promise.allSettled([
  fetchPipelineStats(),
  fetchRecentSubmissions(),
  fetchIntegrationStatus(),
  fetchAiInboxBreakdown(),
]);

results.forEach((result) => {
  if (result.status === "fulfilled") {
    console.log("Loaded:", result.value);
  } else {
    console.error("Failed:", result.reason);
  }
});

Now the dashboard can render the three sections that succeeded and show a quiet error state only where the AI breakdown actually failed. Promise.allSettled is the right call whenever a partial result is genuinely more useful than an all-or-nothing failure.

The event loop isn't just a diagram; it's why setTimeout is deliberately used in real apps

The event loop is the mechanism that lets JavaScript, a language that runs on a single thread, handle asynchronous work without blocking. It continuously checks whether the call stack is empty, and once it is, pulls the next pending callback onto the stack to run, microtasks first, then the task queue where things like setTimeout callbacks wait.

Start with a concept that trips people up: fire and forget.

sendEmail();
console.log("Done");

If sendEmail() starts an asynchronous operation and you don't await it, your code doesn't wait around for it to finish. It starts the operation, moves on immediately, and the email finishes sometime later, off to the side. Compare that to:

await sendEmail();
console.log("Done");

which waits for the email to fully send before moving on. The fire-and-forget version is genuinely useful in production; it's the same pattern behind background jobs that shouldn't block a response, but it comes with a real catch: if that unawaited promise rejects, you get an unhandled rejection nobody's watching for. Fire and forget on purpose, with a .catch() attached, is a deliberate choice. Fire and forget by accident, because you forgot the await, is a bug waiting to surface in production logs.

That same asynchronous mental model is exactly what makes setTimeout more than an interview trivia question. It's genuinely useful, constantly, in real applications.

Showing a temporary success message. Say a form submission on Formgrid succeeds and you want to show "Form created successfully" for three seconds:

function showSuccessMessage() {
  const message = document.querySelector("#success");
  message.style.display = "block";

  setTimeout(() => {
    message.style.display = "none";
  }, 3000);
}

JavaScript doesn't freeze for three seconds waiting for this. It shows the message, keeps doing whatever else it needs to do, and the event loop picks the hide callback back up once the timer's done and the call stack is free.

Debouncing a search box. This is the one that shows up in real products constantly. If a user types "formgrid" one character at a time, you don't want to fire an API request on every keystroke:

let timeout;

function searchUsers(query) {
  clearTimeout(timeout);
  timeout = setTimeout(() => {
    fetch(`/api/users?search=${query}`);
  }, 500);
}

Every keystroke cancels the previous timer and starts a new one. Only once the user actually stops typing for 500 milliseconds does the request go out.

Retrying a failed request after a delay.

async function fetchData() {
  try {
    const response = await fetch("/api/data");
    if (!response.ok) {
      throw new Error("Request failed");
    }
    return await response.json();
  } catch (error) {
    console.log("Retrying...");
    setTimeout(() => {
      fetchData();
    }, 2000);
  }
}

setTimeout here is scheduling future work deliberately, giving a flaky dependency a couple of seconds to recover before trying again, rather than hammering it immediately.

Breaking up expensive work so the page doesn't freeze.

function processChunk() {
  // process some work
  if (moreWork) {
    setTimeout(processChunk, 0);
  }
}

processChunk();

The 0 here doesn't mean "run immediately." It means "let the current work finish and give the event loop a chance to handle anything else that's queued before running this next chunk."

Microtasks jump the queue ahead of setTimeout, even at zero delay

Here's the example that actually separates people who've memorized the event loop diagram from people who've internalized it. Imagine a user clicks "Generate Report":

console.log("Starting report");

setTimeout(() => {
  console.log("Report notification");
}, 0);

Promise.resolve().then(() => {
  console.log("Update UI");
});

console.log("Request submitted");

The output is:

Starting report
Request submitted
Update UI
Report notification

Not what most people guess on first read. The synchronous lines run first, in order: Starting report, then Request submitted. Then, before the setTimeout callback gets anywhere near the call stack, the promise's .then() callback runs, because promise callbacks go into the microtask queue, and the microtask queue is fully drained before the event loop even looks at the task queue where setTimeout callbacks live. Only after that does Report notification finally run.

This is exactly why a setTimeout(fn, 0) never means "run this immediately." It means "run this after the current synchronous code finishes, and after every pending microtask has already run." Debugging unexpected execution order in a React app, a Node service, or anything mixing promises with timers almost always comes back to this exact ordering.

If you're asked about this in an interview, debouncing is the strongest real-world example for setTimeout specifically, and this report generation example is the strongest one for explaining why microtasks and macrotasks aren't the same queue.

any versus unknown in TypeScript

any and unknown are both TypeScript types that can hold a value of any shape. The difference is what TypeScript does with that value afterward: any turns off type checking for it entirely, while unknown requires you to narrow it, prove what it actually is, before you're allowed to use it.

any tells TypeScript: don't check this value, I know what I'm doing.

let value: any = "hello";
value.foo.bar.baz();

TypeScript won't say a word about this. JavaScript will still crash at runtime because a string doesn't have .foo.bar.baz(), TypeScript just isn't watching anymore once something is typed any.

unknown takes the opposite position: I don't know what this is yet, so prove it before you use it.

const response = await fetch("/api/user");
const data: unknown = await response.json();

You don't actually know that the server returned what you expected, just because the request succeeded. Typing this any tells TypeScript to trust it completely. Typing it unknown forces you to check before you can touch it:

if (
  typeof data === "object" &&
  data !== null &&
  "name" in data
) {
  console.log(data.name);
}

Once narrowed like this, TypeScript trusts you again, but only inside that branch, and only as far as what you actually checked for.

This matters most at boundaries you don't control:

Your TypeScript application
          ↓
     External API
          ↓
        JSON
          ↓
       unknown
          ↓
   Validate or narrow
          ↓
     Trusted data

API responses, user input, third-party libraries, anything read from a database or a file, none of it should be trusted at the type level just because it compiled. unknown forces the check. any lets you skip it and find out at runtime instead, usually in production, usually at a worse time than during development.

The short version worth remembering: any says trust me, TypeScript stops protecting you. unknown says I don't know yet, TypeScript makes you prove it.

Generics in TypeScript

Generics let you write a function, class, or interface that works with more than one type while still keeping full type information, using a placeholder type, conventionally written T, that gets filled in with a real type at the point where the code is actually used.

The idea behind generics is simpler than the syntax makes it look: write code once, and let it preserve whatever specific type it's handed, instead of losing that information.

Without generics:

function first(items: any[]) {
  return items[0];
}

const result = first([1, 2, 3]);

result is typed any here. The function works, but you've thrown away the fact that you started with an array of numbers.

With a generic:

function first<T>(items: T[]): T {
  return items[0];
}

const number = first([1, 2, 3]); // T = number
const name = first(["Allen", "John"]); // T = string

<T> is a placeholder: give me a type, and I'll use that exact type everywhere I've written T. TypeScript figures out what T is from what you actually pass in, and carries that information through to the return type.

The most common real-world shape of this is an API response wrapper:

interface ApiResponse<T> {
  data: T;
  success: boolean;
  message?: string;
}

const response: ApiResponse<User> = {
  success: true,
  data: { id: 1, name: "Allen" },
};

ApiResponse<User>, ApiResponse<Product>, and ApiResponse<Order> all reuse the same interface, fully typed, instead of writing three nearly identical ones.

The same idea shows up just as often on the frontend, in a reusable table or list component:

<DataTable<User> data={users} />
<DataTable<Product> data={products} />

Same component, same rendering logic, but each usage stays fully typed to the data it's actually given. This is why generics show up everywhere in API clients, reusable components, and utility functions in general; they're the mechanism that keeps one piece of code reusable without becoming untyped in the process.

Where this connects

None of these ideas are actually separate from each other. const and let are about being explicit regarding what's allowed to change. Closures are about a function remembering the scope it was created in, even after that scope has technically finished running. Promise.all and Promise.allSettled are both about running independent work concurrently; they just disagree on what to do when one piece fails. The event loop underneath all of it decides the actual order any of this code runs in: synchronous first, then every microtask, then the task queue. unknown exists because you sometimes genuinely don't know a type yet and need to prove it before using it. Generics exist because you often do know the type at the call site and don't want to throw that information away by writing something that treats everything as any.

That's the pattern worth carrying into the next post in this series: data structures, algorithms, and testing as they actually show up in production, not as isolated interview trivia.

If there's a concept here you'd explain differently, or a production example you think makes any of this land better, I'd like to hear it. Reach me at allen@formgrid.dev.

NestJS for Express Developers: A Practical Guide, With Prisma ORM

Allen Jones — Sat, 05 Sep 2026 22:37:41 +0000

I've spent years building backends in Express. NestJS looks different on the surface, but here's the thing nobody tells you clearly enough: if you already know Express, you don't need to learn backend development again. You need to learn how NestJS organizes the things you already know how to do

At first, NestJS looks like a lot more ceremony for the same result. A simple route handler turns into a controller class, a service class, decorators everywhere, and a module wiring them together. But once you understand why each piece exists, none of it feels like ceremony anymore; it feels like structure you were probably improvising by hand in every Express project anyway.

This post is the explanation I wish I'd had on day one, mapped directly against Express, using Prisma instead of TypeORM, since that's the ORM I already use in production.

The one-sentence version

Think of NestJS as:

Express, plus TypeScript, plus dependency injection, plus modules, plus decorators, plus enforced architecture.

In Express, you might write:

app.post('/users', async (req, res) => {
  const user = await userService.create(req.body);
  res.json(user);
});

The same idea in NestJS:

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Post()
  create(@Body() body: CreateUserDto) {
    return this.usersService.create(body);
  }
}

More characters, same idea. The rest of this post is about why that extra structure exists and when it earns its keep.

The project structure

Scaffold a new project, and you'll get something like this:

nest-api/
├── src/
│   ├── app.controller.ts
│   ├── app.controller.spec.ts
│   ├── app.module.ts
│   ├── app.service.ts
│   └── main.ts
├── test/
├── package.json
├── tsconfig.json
└── nest-cli.json

Four files matter to start: main.ts, app.module.ts, app.controller.ts, app.service.ts. Everything else is scaffolding you'll grow into.

main.ts is your entry point:

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT ?? 3000);
}

bootstrap();

If you're coming from Express, this is your const app = express(); app.listen(3000);, just bootstrapped from a root module instead of a bare instance. NestFactory.create(AppModule) is Nest reading your entire application's shape from one root module and building it from there.

app.module.ts is the first genuinely unfamiliar concept:

@Module({
  imports: [],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Hold off on fully understanding modules yet; they'll make more sense once you've seen a controller and a service in place.

The architecture

                HTTP Request
                     │
                     ▼
              ┌─────────────┐
              │   Module    │
              └──────┬──────┘
                     │
                     ▼
              ┌─────────────┐
              │ Controller  │
              └──────┬──────┘
                     │
                     ▼
              ┌─────────────┐
              │   Service   │
              └──────┬──────┘
                     │
                     ▼
              ┌─────────────┐
              │   Prisma    │
              └──────┬──────┘
                     │
                     ▼
              ┌─────────────┐
              │ PostgreSQL  │
              └─────────────┘

The pieces worth knowing, roughly in the order you'll actually meet them:

Module: organizes a feature
Controller: handles HTTP requests
Service: contains business logic
DTO: describes and validates incoming data
Guard: controls authentication and authorization
Pipe: validates or transforms input
Interceptor: wraps or transforms request and response behavior
Middleware: the same concept as Express middleware
Dependency injection: Nest supplies each class the dependencies it needs, instead of you constructing them by hand

Don't try to hold all of these at once. Controllers and services get you most of the way there.

Your Express knowledge maps directly

This is genuinely the fastest way to internalize it.

Express	NestJS
`app.get()`	`@Get()`
`app.post()`	`@Post()`
`req.params`	`@Param()`
`req.body`	`@Body()`
`req.query`	`@Query()`
`res.json()`	`return`
Middleware	Middleware
Router	Controller
Service modules	Providers and services
Manual dependency passing	Dependency injection
Validation middleware	Pipes
Auth middleware	Guards
Error middleware	Exception filters
Router organization	Modules

Express:

router.get('/users/:id', async (req, res) => {
  const user = await usersService.findById(req.params.id);
  res.json(user);
});

NestJS:

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get(':id')
  findById(@Param('id') id: string) {
    return this.usersService.findById(id);
  }
}

The NestJS version is saying, out loud, in the type system: this class handles /users, and this method handles GET /users/:id. That's the whole trade the extra syntax is making: implicit routing conventions become explicit, checkable structure.

Controllers

This is where you'll feel most at home immediately.

@Controller('users')
export class UsersController {
  @Get()
  findAll() {
    return [];
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return { id };
  }

  @Post()
  create(@Body() body: any) {
    return body;
  }

  @Delete(':id')
  remove(@Param('id') id: string) {
    return { id };
  }
}

That's the equivalent of router.get('/users', ...), router.get('/users/:id', ...), router.post('/users', ...), and router.delete('/users/:id', ...). Nothing conceptually new here.

Services, where Nest starts diverging

In Express you might write:

const userService = {
  async findAll() {
    return db.user.findMany();
  },
  async findOne(id: string) {
    return db.user.findUnique({ where: { id } });
  },
};

In NestJS:

@Injectable()
export class UsersService {
  async findAll() {
    return [];
  }

  async findOne(id: string) {
    return { id };
  }
}

@Injectable() is the important part. It tells Nest that this class can be managed by Nest's dependency injection system. Your controller then does this:

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}
}

Notice what's missing: const usersService = new UsersService() never appears anywhere. Nest creates it and hands it to the controller. That's dependency injection, and it's worth its own section, because it's the concept that actually changes how you think about structuring an app.

Modules

A module groups related functionality into a feature boundary.

src/
├── users/
│   ├── users.controller.ts
│   ├── users.service.ts
│   ├── users.module.ts
│   └── dto/
├── auth/
│   ├── auth.controller.ts
│   ├── auth.service.ts
│   └── auth.module.ts
└── app.module.ts

@Module({
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

@Module({
  imports: [UsersModule],
})
export class AppModule {}

Thinking about this against Formgrid,s actual feature set is a useful exercise, even without rebuilding it in Nest: auth, users, forms, leads, integrations, webhooks, billing, and notifications would each map cleanly to its own module. That boundary is exactly what makes Nest attractive once a SaaS codebase grows past the size where "everything imports everything" stops being manageable in a flat Express app.

DTOs and validation

Instead of the shapeless @Body() body: any, you define what's actually expected:

export class CreateUserDto {
  name: string;
  email: string;
  password: string;
}

Combined with class-validator, this becomes real, enforced validation instead of a type hint:

import { IsEmail, IsString, MinLength } from 'class-validator';

export class CreateUserDto {
  @IsString()
  name: string;

  @IsEmail()
  email: string;

  @MinLength(8)
  password: string;
}

Nest validates incoming requests against this automatically, which replaces a fair amount of hand-rolled validation middleware you'd otherwise be writing and maintaining yourself in Express.

Pipes

Pipes transform and validate input before it reaches your handler.

@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) {
  return this.usersService.findOne(id);
}

A URL parameter arrives as the string "123". The pipe converts it to the number 123 before your method ever sees it, and throws an appropriate exception automatically if the value isn't valid in the first place.

Exceptions

Express:

return res.status(404).json({ message: 'User not found' });

NestJS:

throw new NotFoundException('User not found');

async findOne(id: string) {
  const user = await this.prisma.user.findUnique({ where: { id } });
  if (!user) {
    throw new NotFoundException('User not found');
  }
  return user;
}

Nest turns that thrown exception into the correct HTTP response for you. You also get BadRequestException, UnauthorizedException, ForbiddenException, ConflictException, and InternalServerErrorException out of the box, all consistent, all readable at the point they're thrown instead of buried in a response call.

Guards

You'll meet these implementing authentication:

@UseGuards(AuthGuard)
@Get('profile')
getProfile() {
  return this.usersService.getProfile();
}

A request either fails the guard and never reaches the controller, or passes it and proceeds normally. That's generally cleaner than scattering an authentication check inside every individual Express route handler.

Interceptors

These can wait until you actually need them. They wrap around a controller's execution, useful for logging, response transformation, timing, or caching:

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  intercept(context: ExecutionContext, next: CallHandler) {
    console.log('Request started');
    return next.handle();
  }
}

Middleware

Good news here: you already know this one.

@Injectable()
export class LoggerMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    console.log(req.method, req.url);
    next();
  }
}

This transfers from Express almost without translation.

Wiring up Prisma instead of TypeORM

Most NestJS material defaults to TypeORM, but if you're already running Prisma, there's no reason to switch ORMs just to learn a framework. A thin PrismaService is all it takes to bring Prisma into Nest's dependency injection system:

@Injectable()
export class PrismaService extends PrismaClient {
  async onModuleInit() {
    await this.$connect();
  }
}

Then your service depends on it like anything else:

@Injectable()
export class UsersService {
  constructor(private readonly prisma: PrismaService) {}

  findOne(id: string) {
    return this.prisma.user.findUnique({ where: { id } });
  }
}

And the module wires both together:

@Module({
  controllers: [UsersController],
  providers: [UsersService, PrismaService],
})
export class UsersModule {}

Nest handles the application's structure and dependency graph. Prisma handles the database layer. Neither one needs to know much about the other.

Understanding dependency injection: why @Injectable() actually exists

This is the concept that took me the longest to actually feel, rather than just memorize, so it's worth its own deep section.

Here's the honest question: Express works completely fine without anything like @Injectable(). So why does Nest need it?

Express: you are the dependency injection system

Suppose you have this:

class EmailService {
  sendEmail() {
    console.log('Sending email...');
  }
}

class UsersService {
  constructor(private emailService: EmailService) {}

  createUser() {
    this.emailService.sendEmail();
  }
}

class UsersController {
  constructor(private usersService: UsersService) {}

  createUser() {
    return this.usersService.createUser();
  }
}

In Express, you wire this by hand:

const emailService = new EmailService();
const usersService = new UsersService(emailService);
const usersController = new UsersController(usersService);

app.post('/users', (req, res) => {
  usersController.createUser();
  res.send('Created');
});

No @Injectable() anywhere, because none is needed. You are the dependency injection system: you decide what gets created, in what order, and what gets passed into what. TypeScript's constructors already support this pattern natively; nothing about it is Nest-specific.

What NestJS actually adds

NestJS's pitch is essentially: why keep wiring this by hand? So instead:

@Injectable()
export class EmailService {
  sendEmail() {
    console.log('Sending email...');
  }
}

@Injectable()
export class UsersService {
  constructor(private emailService: EmailService) {}

  createUser() {
    this.emailService.sendEmail();
  }
}

@Controller('users')
export class UsersController {
  constructor(private usersService: UsersService) {}

  @Post()
  createUser() {
    return this.usersService.createUser();
  }
}

@Module({
  controllers: [UsersController],
  providers: [UsersService, EmailService],
})
export class UsersModule {}

Now nothing gets manually constructed. Nest resolves the graph itself: the controller needs UsersService, so Nest finds or creates one; that service needs EmailService, so Nest finds or creates that too. @Injectable() is the marker that tells Nest's container "this class is allowed to participate in that resolution," nothing more mystical than that. It isn't a requirement of TypeScript constructors; it's metadata Nest specifically needs to do its job.

Why this matters more as the app grows

At three classes, manual wiring in Express is completely fine, arguably even clearer, since you can see the whole graph in one place. The value of letting Nest do it shows up once the graph gets genuinely large.

Picture something the shape of Formgrid's dependency tree, hypothetically, if it were structured this way:

UsersController
      │
      ├── UsersService
      │        │
      │        ├── UsersRepository → DatabaseService
      │        ├── EmailService → ResendService
      │        └── PaymentService → PaddleService

Wired by hand in Express, that's:

const database = new DatabaseService();
const repository = new UsersRepository(database);

const resend = new ResendService();
const email = new EmailService(resend);

const paddle = new PaddleService();
const payment = new PaymentService(paddle);

const users = new UsersService(repository, email, payment);
const controller = new UsersController(users);

That's manageable once. It gets genuinely unpleasant at real scale, a hundred services deep, where any one of them needing an additional dependency means updating every place that constructs it, in the right order, every time.

In Nest, you just declare what each class needs:

constructor(
  private repository: UsersRepository,
  private email: EmailService,
  private payment: PaymentService,
) {}

And the container resolves and constructs the entire tree for you, in the correct order, every time.

The actual insight

Constructors aren't the difference between Express and NestJS. Both let you declare constructor(private emailService: EmailService) and both will happily accept it; that part is plain TypeScript, nothing framework-specific about it either way.

The difference is who is responsible for calling those constructors and supplying what they need. In Express, that's you, by hand, every time. In NestJS, that's the container, once you've told it, via @Injectable() and a module's providers array, which classes it's allowed to manage.

That's the whole idea @Injectable() exists to express. Everything else in Nest, controllers, modules, guards, pipes, is really just structure built on top of that one core mechanism.

Where this leaves you

If you already know Express well, none of this is new backend knowledge; it's a new way of organizing backend knowledge you already have. Controllers are routers with better names. Services are the business logic you were already separating, formalized. Modules are the feature folders you were probably already creating by convention, now enforced by the framework instead of by team discipline.

The place NestJS earns its extra ceremony is scale and team size; a large, long-lived API with many contributors benefits from a framework insisting on structure. A small API, a quick internal tool, or a solo project where you already have the discipline to keep things organized may not need it at all. Express isn't wrong for those; it's just a different tradeoff.

If you've made the same jump from Express to NestJS, or gone the other way, I'd like to hear what actually clicked for you. Reach me at allen@formgrid.dev.

I'm Allen, a full-stack TypeScript engineer and the founder of Formgrid and SheetRocket. I write about real production engineering from products that people actually pay for. More at jonesstack.com.

I Built a Next.js Auth Boilerplate That Saves Developers Two to Four Weeks of Setup Time

Allen Jones — Tue, 01 Sep 2026 20:11:29 +0000

Every time I started a new project, whether it was Formgrid, Sheetrocket, or a client build, the first week or two disappeared into authentication. Email verification tokens. Password reset flows. NextAuth configuration. A Prisma schema for users and sessions. Setting up the Google OAuth consent screen. Middleware for protected routes.

None of that is intellectually interesting. All of it is necessary. And it has to be done correctly, because a mistake in auth isn't a bug; it's a security vulnerability with someone's real account attached to it.

After doing this properly from scratch for the fifth time, I stopped. I built it once, the right way, open-sourced it, and made it the starting point for every project after this one.

The result is a production-ready authentication starter kit that gets a new Next.js project from zero to working auth in minutes instead of weeks.

What it includes

Email and password authentication with Zod validation. Not just a signup form, proper server-side validation that catches weak passwords, duplicate emails, and malformed input before any of it reaches the database.

Email verification. New users can't access protected routes until they verify their email, and the verification token expires after 24 hours. Without this, any email address, including ones the signer doesn't actually own, can be used to create an account.

Password reset with secure tokens. The reset token expires after one hour. Without an expiry, a leaked reset link is a permanent vulnerability sitting in someone's inbox forever. The token itself is hashed before it's stored, so even a full database breach doesn't hand over usable reset tokens.

Google OAuth with NextAuth.js v5. Handles the OAuth flow, stores the account link in the database, and merges correctly with an existing email account if the user originally signed up with a password. Getting that merge logic wrong is one of the most common auth bugs I've seen in real production apps.

Protected routes with Next.js middleware. Everything under the dashboard directory is protected automatically. The middleware checks the session and redirects unauthenticated users to login before the page component ever renders; no manual auth check copied into every page.

** Role-based access.** The User model has a role field, defaulting to USER, with support for ADMIN and any other role you want to add. Middleware can gate admin-only routes without touching every protected page individually.

A responsive dashboard layout in Tailwind. A clean starting point for the authenticated UI, so you can start building your actual feature immediately after cloning instead of also designing a dashboard shell first.

The stack, and the honest tradeoffs

Next.js 15 with the App Router. The current standard for React apps with server components and server actions. The App Router changes how auth is wired up compared to the Pages Router, and NextAuth v5 is built specifically for it.

Prisma with MySQL. Type safe queries with automatic migrations. MySQL for wide hosting compatibility, easily swapped for PostgreSQL by changing one line in the Prisma schema and the DATABASE_URL.

NextAuth.js v5. The current major version, with breaking changes from v4. The configuration pattern changed significantly, and most tutorials still floating around online use the old v4 pattern. This boilerplate uses the correct v5 approach.

Resend for transactional email. The most developer-friendly email API I've used. It's what Formgrid runs in production for verification and notification emails. The templates in the boilerplate are plain text and easy to reskin with your own branding.

Tailwind CSS. Utility-first styling that ships zero unused CSS to production.

Three decisions worth explaining, because most tutorials get them wrong

JWT sessions over database sessions

NextAuth supports two session strategies. Database sessions store a session record per login and validate it against the database on every request. JWT sessions encode the session data into a signed token and validate it cryptographically, no database query required.

Database sessions are more revocable; you can kill a session instantly by deleting its record. JWT sessions are faster, since there's no query on every authenticated request, but you can't invalidate one without extra infrastructure sitting on top. The boilerplate uses JWT for simplicity and speed. If your product needs immediate session revocation, for example, kicking someone out the moment their subscription lapses, that's the tradeoff worth knowing before you commit to this pattern.

Hashing verification and reset tokens

Verification tokens and password reset tokens are stored hashed in the database, never in plain text. That means even if someone reads the raw database, they can't use the stored tokens to verify accounts or reset passwords themselves. The plain text token only ever exists in the email link, and it's compared against the hash at submission time. Same principle as password hashing, applied to a temporary token instead of a permanent credential.

Auth checks belong in middleware, not in page components

Next.js middleware runs on the Edge runtime before the page ever renders. Putting the auth check there means a protected page is never rendered for an unauthenticated visitor, not even partially. Putting the check inside the page component instead means the page starts rendering and then redirects, which produces a flash of content the user was never supposed to see. Middleware is the correct place for the gate, not a convenience, but a correctness requirement.

How to use it

git clone git@github.com:allenarduino/nextjs-prisma-auth-boilerplate.git

cd nextjs-prisma-auth-boilerplate

npm install

Copy .env.example to .env and fill in:

DATABASE_URL, your MySQL connection string
NEXTAUTH_SECRET, a random 32-character string; generate one with openssl rand -base64 32
NEXTAUTH_URL, your app's base URL
GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, from the Google Cloud Console after creating an OAuth 2.0 credential
RESEND_API_KEY, from resend.com after creating an account and verifying a sending domain
EMAIL_FROM, the sender address your verification and reset emails go out from, for example Formgrid <no-reply@yourdomain.com>

Then:

npx prisma generate

npx prisma db push

npm run dev

That's the whole setup. From clone to a working signup, verification, login, and password reset flow, in minutes.

What to build on top of it

A SaaS product. The auth layer is done. Add your subscription logic, your core features, and your billing integration. The User model's role field is already there to extend into a subscription tier if you need one.

A client project. Clone it, configure the environment variables for the client's domain and database, restyle the Tailwind to match their brand, and deploy. The auth is production-ready from day one, not a prototype you'll need to harden later.

A side project. Stop spending the first two weeks on auth and start building the part that's actually yours. The boilerplate handles the foundation so you can get to the feature that makes your project worth building in the first place.

How this connects to Formgrid

Formgrid runs a similar auth pattern, built in Express and Prisma instead of NextAuth, but the same principles apply underneath: email verification, hashed tokens, JWT sessions, Google OAuth, protected routes. Building this boilerplate was really just distilling those same patterns, ones already proven in a product real customers pay for, into a shareable starting point for the Next.js ecosystem specifically.

Where it stands right now

The repo has picked up 17 GitHub stars and 9 forks in a short amount of time, which is a decent early signal that the pain point is real and not just mine. You can browse the code at github.com/allenarduino/nextjs-prisma-auth-boilerplate or try the live demo at nextjs-prisma-auth-boilerplate.vercel.app.

Closing

Authentication is never the interesting part of a product. It's the necessary foundation everything else gets built on. Getting it right matters because getting it wrong means real security vulnerabilities attached to real users. Getting it done quickly matters because every week spent on auth is a week not spent on the feature that actually makes your product worth using.

Clone the repo, configure the environment, and go build the interesting part.

If you use it on a project, or find a way to improve it, I'd genuinely like to hear about it. The repo is open for contributions and issues at github.com/allenarduino/nextjs-prisma-auth-boilerplate. Reach me at allen@formgrid.dev.

I'm Allen, a full-stack TypeScript engineer and the founder of Formgrid and Sheetrocket. I write about real production engineering from products that people actually pay for. More at jonesstack.com.

I Deployed a Backend API on Vercel and Here Is What Broke

Allen Jones — Mon, 31 Aug 2026 10:19:12 +0000

The backend was for one of my
projects, Sheetrocket, a tool that turns any Google Sheet into a REST API or a set of no-code embeddable widgets.

The idea is simple: developers connect
a Google Sheet and get a REST endpoint that returns their
data as JSON, while non-technical users display that same data
on any website as cards, catalogues, or tables without writing a single line of code. Update the sheet, and everything stays in sync automatically.

The problem is that Google Sheets enforces rate limits on API requests. If every request to a Sheetrocket endpoint triggered a fresh call to the Google Sheets API, I would hit those limits fast, especially under any real traffic. The obvious solution was in-memory caching: fetch the sheet data once, store it in a Map, return the cached version on subsequent requests, and only refresh from Google when the cache expired.

I had built exactly this pattern before, on long-running servers, without any issues. The cache sat at the module level, warmed up on the first request, and served every request after that from memory. Fast, simple, and it kept Google Sheets API calls to a minimum.

Vercel felt like the obvious deployment choice. One-click deploy from GitHub, a generous free tier, and I was already using Next.js for other work. It barely felt like a decision.

const cache = new Map();

export default async function handler(req, res) {
  if (cache.has(req.query.id)) {
    return res.json(cache.get(req.query.id));
  }
  const data = await fetchFromDatabase(req.query.id);
  cache.set(req.query.id, data);
  res.json(data);
}

Then in production, the cache never worked. Every request was hitting the Google Sheets API directly, consuming rate limit quota on every single call. The cache that worked perfectly in local development was silently empty in production every time.

I spent time assuming it was a bug in my caching logic before I realized the problem had nothing to do with my code at all.

The problem was not the code. It was where the code was running.

And the cost of that was not just slower responses; it was correctness. A cache failure here meant real Google Sheets API quota burning on every request instead of most requests getting served from memory. Under any real traffic, that means hitting Google's rate limit, getting throttled, and returning errors instead of sheet data. Visitors don't see a slow widget at that point; they see a broken one.

Why this happens

Vercel runs Next.js API routes as serverless functions, not as a traditional server that starts once and stays alive. A serverless function spins up when a request arrives and shuts down when it goes idle.

My in-memory cache lived inside that function instance. When the instance shut down, the cache went with it. When a new instance started, the cache was empty again. The code correctly populated the cache on the first request, but by the time the next request came in, Vercel may well have spun up a fresh instance with no memory of it at all.

This is why the same code behaves differently locally versus on Vercel. Locally, the Next.js development server runs as a long-running process. It starts once and stays alive, so the cache persists across requests because the same process handles them all. Everything works perfectly in development. On Vercel, the same code runs as serverless functions. The cache works sometimes, when the same warm instance happens to handle consecutive requests. It fails other times, when a cold instance with an empty cache picks up the request instead. The behavior is inconsistent, and it depends entirely on Vercel's internal instance management, which the developer has no visibility into or control over.

One sentence covers all of it: Vercel runs API routes as serverless functions, and serverless functions have no guaranteed persistent memory between requests. An in-memory cache assumes the same process handles every request. On Vercel, that assumption is simply wrong.

Before I go further: Vercel has genuinely improved here. Fluid compute now keeps functions warm between requests for longer and reduces cold starts meaningfully compared to a couple of years ago. This isn't a case against Vercel as a platform. It's a case about matching an execution model to a problem, and a pure JSON API with in-memory state and no rendering is not the problem serverless was built to solve.

Everything else that breaks, for the same reason

Every problem in this post traces back to one root cause: serverless functions are stateless, and in-memory state requires a stateful process to hold it.

Rate limiting

A common pattern tracks how many requests an IP address has made in a rolling window, using an in-memory counter.

const requestCounts = new Map();

function isRateLimited(ip) {
  const count = requestCounts.get(ip) || 0;
  if (count >= 10) return true;
  requestCounts.set(ip, count + 1);
  return false;
}

On a long-running server, this works exactly as written. On serverless, each function instance keeps its own counter. Ten concurrent requests might land on ten different instances, each with a counter showing one request. A limit meant to be ten requests per minute is effectively multiplied by however many instances Vercel has spun up. The rate limiter isn't broken loudly; it's broken silently, which is worse.

Cold start latency

When a function has been idle, Vercel has to spin up a new instance: load the Node.js runtime, import every module, establish any connections, and only then handle the request. For a simple always-on API expected to respond in milliseconds, that adds latency that is not just slower; it's unpredictable, shifting based on traffic patterns rather than staying consistent.

For an internal tool used sporadically through the day, this means the first person to use it after a quiet stretch always waits longer than everyone after them. For a customer-facing API, it's the opposite of what you'd want: the slowest responses land on whoever arrives after the longest gap, often the exact users you'd least want to leave with a bad first impression.

Database connection overhead

A long-running server maintains a connection pool to the database once, at startup. A pool of ten connections can handle thousands of requests a second by reusing those same ten connections over and over.

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
  max: 10,
});

app.get('/users', async (req, res) => {
  const result = await pool.query('SELECT * FROM users');
  res.json(result.rows);
});

A serverless function doesn't get that luxury. Each cold start either opens a fresh connection or competes with other invocations over a shared pool. If a traffic spike causes Vercel to spin up 50 instances and each one opens its own connection, you've consumed 50 of your available database connections almost instantly. PostgreSQL's free and small paid tiers often cap connections somewhere between 25 and 100. The 51st instance simply can't connect, and that request fails, not because of load on the database itself, but because of how many separate processes are all trying to reach it at once.

Background jobs

If you want to kick off a background task when a request arrives and let it keep running after the response is sent, Vercel will kill that task the moment the function shuts down. Fire-and-forget patterns that work cleanly on a long-running server don't work on serverless without extra infrastructure to keep the job alive independently.

Formgrid relies on exactly this pattern for four background operations after every form submission: Google Sheets sync, Notion sync, AI analysis, and the email notification itself. None of them block the HTTP response the visitor sees, and all of them keep running after that response is sent. That only works because Formgrid runs on a long-running Express server on Render, where the process stays alive long enough to actually finish the background work instead of being torn down mid-task.

When Vercel and serverless are genuinely the right call

This isn't an argument that serverless is bad; it's specific to what it's optimized for. Serverless is a strong choice for:

Static sites and marketing pages, where there's no state to maintain
Server-side rendered pages with Next.js, where rendering happens fresh per request anyway
Edge functions serving geographically distributed, low-latency responses
Webhooks and event-driven functions that run occasionally, not continuously, with no state requirements
Bursty, unpredictable workloads where paying per request beats paying for idle time
Rapid prototyping, where deployment simplicity matters more than performance tuning

A decision framework

A short set of questions, each pointing toward an answer:

Does your API maintain state between requests, caches, counters, session data? Yes: long-running server. No: either works.

Does it hold open connections to a database or external service that are expensive to establish? Yes: long-running server with connection pooling. No: either works.

Do you need consistent sub-100ms response times regardless of traffic patterns? Yes: long-running server. No: serverless is acceptable.

Do you need background processing that continues after the response is sent? Yes: long-running server. No: either works.

Is your traffic bursty and unpredictable, and is paying per request more important than consistent latency? Yes: serverless is the better economic choice. No: a long-running server is usually more cost-effective and predictable.

Is this a Next.js app with both a frontend and API routes, where the frontend genuinely benefits from Vercel's CDN and deploy experience? Yes: Vercel makes sense; the frontend benefits usually outweigh the API route limitations for most apps. No, pure API only: a long-running server on Render or Railway is almost always the better choice.

Platform comparison, with real costs

Render: the free tier spins down after inactivity, which reintroduces the same cold start problem you're trying to escape. The paid tier, $7 a month, keeps the server always on with consistent performance. Formgrid runs on a $7 a month Render instance serving around 1,000 daily visitors.

Railway: a free tier with a $5 monthly credit, then usage-based, roughly $5 to $10 a month for a small always-on API. Good developer experience, flexible for more complex setups.

Fly.io: a free tier is available, runs containers globally, a solid option for geographic distribution without full serverless complexity.

Hetzner: around 4 euros a month for a small VPS with 2GB of RAM. The cheapest option if you're comfortable managing your own server, full control, no abstraction layer.

DigitalOcean App Platform: a free tier available, managed containers, an experience fairly similar to Render.

The hybrid approach

Plenty of real applications use both, and it's worth naming because it's the actual nuance most take on this miss. A Next.js frontend on Vercel handles the marketing site, while a separate, long-running Express API on Render handles the backend that needs connection pooling and background processing. Vercel does what it's built for. Render does what it's built for.

Formgrid is built this way. The API is a long-running Express server on Render. The dashboard is a React SPA. They're separate services, deployed separately, because each one has genuinely different infrastructure requirements.

Closing

The infrastructure decision you make at the start of a project is one of the hardest to undo later. Not because the migration itself is usually technically complex; it typically isn't. But because you have to do it without anyone noticing.

Understanding what serverless is actually optimized for, before reaching for it because it feels familiar, is one of the most valuable habits you can build as an engineer. Not because serverless is wrong. Because the right tool for the right job beats the familiar tool for every job, every time.

If you've hit this same wall, or made the same call and lived to tell about it, I'd genuinely like to hear what you learned. Reach me at allen@formgrid.dev.

I'm Allen, a full-stack TypeScript engineer and the founder of SheetRocket, a tool that turns Google Sheets into REST APIs and embeddable widgets, and Formgrid, an open-source form backend and lead pipeline. Both run on long-running Express servers on Render. I write from what actually happens in production, not from theory. More at jonesstack.com.

How to Send Form Submissions to Notion Automatically Without Zapier

Allen Jones — Sat, 29 Aug 2026 22:59:12 +0000

If your team lives in Notion, your website contact form probably does not fit into that workflow.

A visitor fills out your form. The submission lands in an email inbox somewhere, separate from the Notion workspace where your team actually manages clients, projects, and leads. Someone has to notice the email, copy the details, and paste them into Notion by hand. On a busy week, that step gets skipped. The enquiry sits in an inbox nobody checks until it is too late to reply.

Moving data from email into Notion manually does not scale, and it is exactly the kind of small, repeated task that quietly costs you leads.

This post walks through how to send form submissions straight into a Notion database automatically, with no Zapier account, no custom code, and no manual copying, using Formgrid's native Notion integration.

Short Version

Skip Zapier and custom webhook code entirely. Create your form, connect your Notion workspace once through Notion's own authorization screen, choose which database submissions should go into, and every new entry appears as a page automatically. Properties are created for you from your form fields on the first submission.

Try it free at formgrid.dev, or keep reading for the full walkthrough with screenshots.

Why This Is Harder Than It Should Be

If you have looked into connecting a form to Notion before, you have probably run into one of these:

Zapier. It works, but it costs $20 or more per month on top of whatever you already pay for your form tool. You also have to build the Zap yourself, and Zaps break quietly when either tool changes something on their end. There is also a delay between the form submission and the Notion entry showing up, since Zapier checks for new data on a schedule rather than instantly.

Manual export. Download a CSV of your submissions and import it into Notion. This works exactly once, then becomes a task you have to remember to repeat. It is never real-time, and it is the first thing to get skipped when you are busy.

Notion integrations built into some form tools. A few form builders offer a native Notion connection, but only for forms built inside that tool. If you already have an HTML form on your website, or a form built somewhere else, those integrations are not an option for you.

Building it yourself. Writing a webhook handler that receives your form submission and inserts it into Notion through their API is a real option if you can code, but it means hosting backend code, handling authentication with Notion, and maintaining it going forward. That is a lot of ongoing work for something that should be a checkbox.

None of these are good defaults for a team that just wants their form submissions to show up in Notion the moment someone submits.

Who This Is For

This guide is for anyone who manages their work in Notion and wants form submissions to land there automatically.

Agencies and freelancers who track clients and projects in Notion and want new enquiries to appear as a page they can move into their existing workflow.

Small teams who use a Notion database as their shared source of truth and do not want leads sitting in an inbox separate from everything else they manage.

Course creators and community builders who run their whole operation out of Notion and want enrollment or membership enquiries to show up right alongside the rest of their workspace.

Anyone replacing a Zapier setup who wants the same result without the extra monthly cost or the Zap that needs maintaining.

If your team already lives in Notion, this integration was built for that exact workflow.

The Simple Alternative

Formgrid, an open-source form backend and no-code form builder, now has a native Notion integration built directly into the platform.

You connect your Notion workspace once, using Notion's own authorization screen, the same one you have seen when connecting other tools to Notion. From that point on, every form submission automatically creates a new page in the Notion database you choose. No Zapier account, no webhook to write, no manual export.

It works whether you build your form using Formgrid's no-code form builder or you already have an existing HTML form on your website pointed at a Formgrid endpoint. Either way, the moment someone submits, the same submission that triggers your email notification also creates a page in Notion, in real time.

How Notion Databases and Pages Work, in Plain Terms

Before the walkthrough, here is the short version of what you are actually setting up.

In Notion, a database is like a spreadsheet. Each row in that spreadsheet is called a page, and you can open any page to read the full details behind it. Each column in the spreadsheet is called a property, things like Name, Email, or Message.

When a form is submitted, Formgrid creates one new page in your chosen database, essentially adding one new row. Each field from your form becomes a property on that page: your Name field becomes a Name property, your Email field becomes an Email property, and so on. The submission time is added automatically as a property called Submitted At.

You do not need to set any of this up manually. The properties are created automatically the first time a submission comes in, matched to your form's fields.

Step by Step: Connecting Formgrid to Notion

Step 1: Sign Up at Formgrid

Head to formgrid.dev and sign up using Google or email. No credit card required.

Step 2: Create Your Form

Once you are logged in, you will land on your dashboard. Click New Form to get started.

You can either build a form from scratch using Formgrid's drag-and-drop form builder, or, if you already have an existing HTML form on your website, create a form and use the endpoint URL it gives you instead. Both work the same way with the Notion integration.

Step 3: Open the Integrations Tab

Click into your form to open its details page, then click the Integrations tab.

Step 4: Find the Notion Section

Scroll down to the Notion integration section and click Connect with Notion.

Step 5: Authorize Formgrid in Notion

You are redirected to Notion's own authorization screen. This is Notion's official page, not a Formgrid page, so it looks exactly like the consent screen you have seen when connecting any other tool to Notion. Choose the workspace and the pages or databases you want to share with Formgrid, then confirm.

Step 6: Choose Your Database

Back in Formgrid, you will see a dropdown listing every Notion database you shared with the integration in the previous step. Select the one where you want form submissions to appear.

Step 7: Confirm the Connection

Click Connect. The Integrations tab now shows a connected state, including the name of the Notion database you selected, along with the option to disconnect at any time.

Step 8: Test It

Fill out your form yourself, either on your live website or through the Formgrid shareable link. Within moments, three things happen at once, automatically, with no extra setup on your part.

You get an email notification instantly, and it is not a generic "new submission" email.

Formgrid analyzes every submission with AI before the email arrives, so the subject line already tells you what kind of submission it is before you open it:

[Hot Lead] Contact Form
[Likely Spam] Contact Form
[Sales Pitch] Contact Form
[Support Request] Contact Form
[General Enquiry] Contact Form

You know what arrived without opening the email. Spam gets deleted in one tap. A hot lead gets opened and answered immediately. The AI also writes a summary inside the email body, so you understand what the person needs without reading through every field yourself.

At the same time, a new page appears in your connected Notion database with every field from your submission filled in as a property.

The same submission also becomes a tracked lead in your Formgrid dashboard, starting at New, which you will see in the next section.

That is the entire setup. From here, every future submission to this form lands in Notion automatically, with no further steps.

The Full Picture: What Happens to Every Submission

It is worth being explicit about all three things that happen simultaneously, since most people searching for a Notion integration are only thinking about the first one.

Instant email notification with AI analysis. Every submission is analyzed before the email reaches your inbox, so the subject line tells you what it is: a hot lead, likely spam, a sales pitch, or a support request, before you open it. A short AI summary inside the email tells you what the person actually needs.

Automatic Notion database entry. At the same moment, a new page is created in your connected database with the full submission as properties, organized in the workspace your team already uses.

Lead pipeline tracking. The same submission also becomes a tracked lead inside Formgrid, moving through New, Contacted, and Converted as you work it. You can add a private note, set a follow-up reminder that emails you on the day you need to act, and see your conversion rate over time. If you reply to a lead directly from the Formgrid dashboard using a connected Gmail account, the status updates to Contacted automatically and the reply is logged on that lead's timeline.

You get the speed of an email, the organization of Notion, and a managed follow-up workflow, all from one submission, with no manual step connecting any of them.

How Notion and Formgrid Work Together

It helps to think of these as two different jobs rather than two tools doing the same thing.

Notion is where you organize and search your submission data. Filter by date, search by email, open a page to read the full message, or build a Notion view on top of it, exactly the way your team already works with everything else in your workspace.

Formgrid is where you manage the human side of each enquiry. Pipeline stages, follow-up reminders, conversion tracking, AI categorization, and replying from your own Gmail address without leaving the dashboard. None of that exists natively inside Notion.

Connected, your data lives in Notion, and your workflow runs in Formgrid. Most people come looking for a way to get form data into Notion and only discover the follow-up side once they see it working, which tends to be the part that actually justifies paying for it.

Managing Your Connection

Once connected, the Integrations tab shows your connection status.

Pause the integration using the Active toggle. When paused, new submissions are still saved to Formgrid but not sent to Notion. Toggle it back on to resume.

Disconnect removes the connection entirely. Your existing Notion pages stay exactly as they are, but new submissions no longer sync.

Troubleshooting

"Could not access this database"

The database was not shared with the Formgrid integration during the Notion authorization step. Reconnect and make sure to select the database you want to use when Notion asks which pages and databases to share.

Properties look wrong or missing

Properties are created automatically from your form's field names on the first submission. If you renamed a field after connecting, new properties are created rather than the old one being renamed, so it is worth connecting the integration after your form fields are finalized.

Submissions not appearing in Notion

Check that the integration is Active in your Integrations tab. If it shows Paused, click the toggle to resume.

How This Compares to Zapier

	Zapier Route	Formgrid Native
Setup time	20 to 40 minutes	Under 5 minutes
Extra cost	$20 or more per month for Zapier	Included with Formgrid Premium
Works with existing HTML forms	Only with extra configuration	Yes, by default
Real time	Depends on Zap frequency	Instant
Technical knowledge	Medium	None

What You Can Do With the Data Once It Is in Notion

Once submissions are landing as pages in your database, you get everything Notion already gives you for free: view all submissions as a table, filter by date or by any property, search by email, sort by most recent, or open an individual submission to read the full message. If your team already manages projects or clients in Notion, new leads now show up right alongside that work instead of living in a separate inbox.

Plan Limits

Formgrid's free plan includes 10 Notion pages, one-time, not a monthly reset, along with 10 AI Smart Inbox analyses, also one-time. That is enough to fully test both the Notion integration and the AI categorization, confirm they work with your form, and see exactly what a submission looks like before deciding to upgrade.

The Premium plan, at $12 per month, raises those limits considerably and adds everything else covered in this post:

500 Notion pages per month
1,000 AI Smart Inbox analyses per month
Google Sheets sync, 500 rows per month
Email notifications to up to 3 recipients
Full lead pipeline with custom stages,
  notes, follow-up reminders, and
  conversion rate tracking
Reply to Lead: reply from your own Gmail
  address directly from the dashboard
CSV export and bulk operations

The Business plan, at $29 per month, includes unlimited Notion pages and unlimited Google Sheets sync, alongside everything in Premium.

None of the above requires Zapier, at any plan.

Final Thoughts

If your team runs on Notion, there is no good reason for your form submissions to live somewhere else. Zapier adds a monthly cost and a Zap you have to maintain. Manual export is real work you will eventually forget to do. Writing your own integration means hosting and maintaining backend code for something that should not need it.

Formgrid's Notion integration replaces all of that with a one-time connection: authorize once, pick your database, and every submission from that point forward becomes a page automatically, in real time, with no further setup.

Most people set this up because they want their data in Notion. What tends to keep them on the Premium plan is everything running alongside it: the AI-categorized subject lines, the lead pipeline, and replying to a lead without leaving the dashboard. That is the same pattern behind Formgrid's Google Sheets integration: people come for the spreadsheet sync and stay once they see the rest of the workflow working.

Try it on the free plan first. Ten submissions are enough to see it working end-to-end before you decide whether to upgrade.

Connect your form to Notion at formgrid.dev. No credit card required to start.

I Added AI Lead Classification to My Form Tool Without Slowing Down Submissions

Allen Jones — Fri, 28 Aug 2026 14:42:19 +0000

One of the things I've learned from running a SaaS is that a feature can be technically easy and still be a difficult production problem.

Form submissions are a good example. My product already knew the moment a submission arrived. The harder problem was deciding what deserved a business owner's attention. A genuine customer asking for a quote, a spam bot, an SEO sales pitch, and a support request could all arrive in the inbox looking identical, same subject line, same formatting, with no way to tell which one actually mattered.

I wanted the system to figure out what each submission actually was before the business owner opened the email.

So I built an AI layer that classifies every submission, assigns a priority, generates a summary, and puts that information directly into the notification email and the dashboard.

The interesting part wasn't calling an LLM. It was making the feature cheap enough to run on every single submission, fast enough that it couldn't affect form delivery, and resilient enough that an AI failure could never cause a lost lead.

Here's how I built it.

Why a simple LLM call wasn't enough

The naive version of this feature is easy to picture: submission comes in, call an LLM, wait for the response, attach the result to the notification. That works fine in a demo. It falls apart under a few real constraints:

Latency. This runs on every submission, on every form, for every account on the platform. If the LLM call sits in the request path, a slow model response means a slow form submission, and a visitor filling out a contact form has no idea or reason to care that AI is running behind the scenes. Their form just needs to submit.

Reliability. LLM APIs fail, time out, or rate-limit. If classification is a required step before a submission is accepted, then an AI outage becomes a lost lead, which is the one outcome this feature was never allowed to cause.

Cost at scale. This isn't a one-off classification task; it's every submission, indefinitely. A model chosen because it produced impressive answers in testing can turn into a real cost problem once it's running continuously in production.

Structured, consistent output. I needed a category from a fixed list, a priority level, and a summary, every time, in a format I could parse reliably. Not a flexible chat response I'd have to coerce into structure after the fact.

Each of those ruled out the "just call an LLM inline" version of the feature.

The architecture

The fix was to take the AI entirely off the critical path. The visitor's submission gets accepted and confirmed immediately. The classification happens afterward, as a background step that the request itself doesn't wait on.

                    ┌───────────────┐
                    │  Form visitor │
                    └───────┬───────┘
                            │
                            ▼
                    ┌───────────────┐
                    │ Formgrid API  │
                    └───────┬───────┘
                            │
                   persist submission
                            │
                            ▼
                    ┌───────────────┐
                    │ HTTP response │  ← visitor sees success instantly
                    └───────────────┘

                            │
                     background job
                            ▼
                    ┌───────────────┐
                    │ Gemini Flash  │
                    └───────┬───────┘
                            │
                  classification + priority
                        + summary
                            │
                            ▼
                    ┌───────────────┐
                    │  Update lead  │
                    └───────┬───────┘
                            │
                            ▼
                    ┌───────────────┐
                    │ Notification  │
                    │     email     │
                    └───────────────┘

The visitor never waits on the AI step; they never even know it exists. If the classification job fails or times out, the submission has already been saved, and the business owner still gets notified, just without a category attached. The AI layer can degrade without ever taking the core product down with it.

The lead detail view for the first example below, with category, priority, and summary generated automatically.

Choosing the model

I didn't benchmark models based on which one produced the most impressive-sounding answer. I benchmarked against the actual task: a six-way classification, a priority level, and a two-to-three sentence summary, run on every submission across every account on the platform.

That reframing changed the decision. A larger, more capable model would have added cost and latency without adding accuracy that mattered for a fairly constrained classification problem. I went with Google Gemini Flash; it gave me the speed and the economics the task actually needed, while being more than capable of handling six categories and a summary consistently.

The six categories I landed on, after looking at what actually shows up in a real form inbox:

Potential Customer: Genuine buying or engagement intent
Likely Spam: Automated or irrelevant submissions
Sales Pitch: Someone trying to sell to the business, not buy from it
Support Request: An existing customer with a question or issue
Job Application: Someone applying for a role
General Enquiry: A real message that doesn't fit anywhere else

Each submission also gets a priority, High, Medium, or Low, based on urgency and specificity rather than category alone. A potential customer asking a vague question is Medium. A potential customer asking about pricing for 50 seats by Friday is High.

Handling failure without losing a lead

The rule I held myself to: an AI failure can never cause a lost lead. If Gemini times out, errors, or the account hits its analysis limit for the billing period, the submission still saves, the business owner still gets notified, and it arrives without a category badge instead of breaking anything downstream. The AI layer only ever adds information. It's never allowed to be a dependency the core product relies on to function.

That constraint is also why this couldn't be an inline, request-blocking call in the first place. Once the submission is treated as complete the moment it's persisted, an AI failure downstream literally cannot touch it.

What the classification actually looks like

Abstract categories are easier to trust with real examples. Here's what four different submissions to the same contact form produce:

Submission	Category	Priority	AI summary
"Hi, we're a 40-person agency looking for a form tool with an API. Can you send pricing for the Business plan? We'd want to migrate by the end of the month."	Potential Customer	High	Agency evaluating Business plan for a 40-person team, wants to migrate by end of month, time-sensitive purchase intent.
"I'm an existing customer, my Google Sheets sync stopped working yesterday, can someone help?"	Support Request	High	Existing customer reporting broken Google Sheets sync since yesterday, needs troubleshooting.
"Do you offer a student discount?"	General Enquiry	Low	Prospective user asking about pricing discounts, no urgency indicated.
"hey i can get you to page 1 of google in 30 days guaranteed, reply for more info"	Sales Pitch	Low	Unsolicited SEO service pitch, not a product enquiry.
"asdkjf83 !!! CLICK HERE now4free-followers.xyz buy cheap instagram followers 100% guaranteed !!!"	Likely Spam	Low	Automated or bot-generated submission with no coherent message, promotional link pattern typical of spam.

Same form, same inbox, five completely different submissions, and now five completely different subject lines instead of one identical "New submission" notification for all of them. That's the whole point of the feature: the business owner never has to open the spam or the SEO pitch to know they don't matter, and never risks missing the agency lead because it's buried between them.

What I haven't measured yet

I'd like to be honest about where the data stands rather than make this sound more finished than it is: I don't yet have hard numbers on what percentage of submissions get classified as spam versus genuine leads across accounts, or the exact inference cost per 1,000 submissions at current volume. I'm instrumenting both now, cost per classification and category distribution across real accounts, and I plan to publish those numbers once I have a few weeks of real data behind them rather than guess at them here.

Where it shows up

Once a submission is classified, the result appears in three places:

The email subject line, as a prefix before the form name, [Hot Lead], [Likely Spam], [Sales Pitch], [Support Request], so it's readable without opening the email at all.
The email body, with the priority, category, and full summary.
The dashboard, as a colored badge on every lead row, with a filter to pull up just the high-priority leads or exclude spam entirely.

The clearest way to see it in one place is the leads list itself, all five example submissions from the table above, each carrying its own category badge:

Caption: All example submissions in the leads list, filterable by category.

The form tool behind this

The product this shipped on is Formgrid, an open-source form backend and lead management platform I've been building and running on my own since September 2025, alongside a full-time contract role. Every form submission on Formgrid becomes a tracked lead automatically, and this AI layer, which I've been calling AI Smart Inbox, is the newest piece of that pipeline.

If you want to see it running on a real submission, every account gets 10 free AI analyses to try it with no setup required.

The broader lesson, for me at least: the hard part of shipping AI in a real product usually isn't the model call. It's everywhere around it, keeping it off the critical path, deciding what happens when it fails, and picking a model sized to the actual task instead of the most impressive one available.

Don't Build Your Own Form Backend. Here's What It Actually Costs You.

Allen Jones — Thu, 27 Aug 2026 11:00:51 +0000

Every developer has this thought at some point. "It's just a form. I'll write a quick endpoint, send an email with Resend or SendGrid, and be done in an afternoon."

Then you actually build it.

Two hours in, you have a working POST endpoint. Three days later, you are writing spam filtering rules by hand. Two weeks in, a client asks, "Can you show me all the submissions from last month?" and you realize you never built a dashboard, so you are querying your production database directly to answer a simple question. A month in, you are debugging why half your notification emails are landing in spam because you never set up SPF and DKIM records properly.

None of that was in the "quick afternoon" estimate.

This post explains why building your own form backend is almost always the wrong call, how much unexpected time it can cost you, and what you should use instead.

Why This Feels Like It Should Be Easy

On the surface, a form backend looks trivial. Receive a POST request, read the fields, send an email. That part genuinely does take an afternoon.

The problem is that a form backend that is actually usable in production is not that. It is:

1. An endpoint that accepts submissions
2. Spam and bot filtering
3. Email delivery that does not land in spam
4. A dashboard to view past submissions
5. Storage that does not disappear
6. Rate limiting so one bad actor can't flood you
7. Input validation and sanitization
8. File upload handling, if you need it
9. A way to track what happens after a submission arrives

You do not see most of this list on day one. You see it the first time a bot floods your endpoint, the first time a client asks to see old submissions, or the first time your notification emails start landing in spam because you are sending transactional email from a domain with no reputation.

The Hidden Costs Nobody Budgets For

Spam filtering. The moment your form is public, bots find it. Not eventually, immediately. You will need a honeypot field at minimum, and realistically CAPTCHA or a service like hCaptcha or Cloudflare Turnstile on top of that. Writing spam heuristics that catch crypto spam, disposable emails, and HTML injection without also blocking real users takes real iteration, not a weekend.

Email deliverability. Sending email reliably is its own discipline. SPF, DKIM, DMARC, a sending domain with reputation, retry logic for failed sends, and a fallback for when your email provider has an outage. Get any of this wrong, and your "notification" system silently stops notifying you, which is the worst possible failure mode for a form backend.

A dashboard. The first time someone asks "can I see submissions from before I set up email forwarding" or "can you export the last 200 leads to CSV," you realize you built an endpoint, not a system. Now you are building an admin panel: auth, pagination, search, filtering, export. That is not a form backend feature anymore; that is a small internal product.

Storage and retention. Where do submissions live? For how long? What happens when the database grows? Do you need backups? None of this is form-backend-specific; it is generic infrastructure you now own because you decided to roll your own.

Rate limiting and abuse prevention. Without it, one bad actor can submit your form thousands of times a minute, which either racks up your email sending bill or takes down your database.

GDPR and data handling. If you collect any personal data from a form, and you almost always do, you now have a small compliance surface: right to deletion, data retention policy, and knowing exactly where the data lives. This is easy to ignore until someone asks you to delete their data and you have no clean way to find it.

Ongoing maintenance. Every one of the systems above needs to keep working as your dependencies update, as spam patterns evolve, and as your email provider changes their API. A form backend is not something you build once. It is something you maintain forever, or it slowly rots.

None of this is a knock on your ability to build it. All of it is buildable. The question is whether it is worth building, given that it is not the product you are actually trying to ship.

The Math

Say you are honest about the real scope: endpoint, spam filtering, email delivery, a basic dashboard, and rate limiting. That is not an afternoon. That is realistically two to four days of focused work if you already know what you are doing, longer if you do not.

At any reasonable hourly rate, two to four days of engineering time costs more than a year of a managed form backend, and that is before counting the maintenance time you will keep spending every time something breaks.

DIY form backend:
  2-4 days initial build
  + ongoing maintenance
  + your time debugging deliverability issues
  + your time when a client asks for a feature
    the endpoint does not have

Managed form backend:
  10 minutes to set up
  $0-12/month
  Someone else's job to keep spam filtering,
  deliverability, and uptime working

This is the same tradeoff as writing your own authentication system instead of using an auth provider, or rolling your own payment processing instead of using Stripe. It is not that you cannot build it. It is that building it is rarely the highest-value use of your time, because it is infrastructure, not your product.

When Building Your Own Actually Makes Sense

To be fair, there are real cases where rolling your own is the right call:

You have genuinely unusual requirements
no service can meet

You are building this as the product itself,
not as infrastructure for something else

You have strict data residency or compliance
requirements that require full control

You already have this infrastructure built
for other reasons and reusing it is nearly free

You are doing it deliberately as a learning
exercise, not for a production client site

If none of those apply to you, and for most people building a contact form, a quote request form, or a lead capture form on a client site or their own product, none of them do, a managed service is the better trade every time.

What "Just Use a Service" Actually Looks Like

Here is the entire difference between the DIY approach and using a form backend.

DIY, roughly:

// You write and maintain all of this yourself
export default async function handler(req, res) {
  // validate input
  // check honeypot / run captcha verification
  // rate limit by IP
  // sanitize fields
  // save to a database you provisioned
  // send email via a provider you configured
  // handle delivery failures
  // return a response
  res.status(200).json({ success: true })
}

Using a form backend:

<form action="https://formgrid.dev/api/f/your-form-id" method="POST">
  <input type="text" name="name" placeholder="Your Name" required />
  <input type="email" name="email" placeholder="Your Email" required />
  <textarea name="message" placeholder="Your Message"></textarea>
  <button type="submit">Send Message</button>
</form>

That is the entire integration. No server code. No database to provision. No email service to configure. Spam filtering, delivery, storage, and a dashboard all come with the endpoint.

Setting This Up Takes About Ten Minutes

If you want to see exactly how little is involved, here is the full setup using Formgrid, an open-source form backend, as the example.

Step 1: Create an Account

Head to formgrid.dev and sign up with Google or email. No credit card required.

Step 2: Create a Form and Copy the Endpoint

Click New Form, give it a name, and click Create Form.

On the Overview tab, copy your endpoint URL.

Step 3: Point Your Form at It

Drop the endpoint into your form's action attribute. If you already have a form on your site, this is the only line that changes.

<form action="https://formgrid.dev/api/f/your-form-id" method="POST">
  <input type="text" name="name" required />
  <input type="email" name="email" required />
  <textarea name="message"></textarea>

  <!-- honeypot, invisible to real users -->
  <input type="text" name="_honey" style="display:none" />

  <button type="submit">Send</button>
</form>

Spam filtering, rate limiting, and bot protection are already active. You did not configure any of it.

Step 4: Notifications Are Already On

Nothing to set up here. The email address you signed up with is the default notification address the moment your form goes live. If you want submissions sent somewhere else, like a client's inbox or a shared team address, that is a single field in Settings.

Step 5: Every Submission Is Already a Tracked Lead

This is the part a DIY endpoint never gets to, because building it is a whole separate project. Every submission lands in a dashboard automatically, with a status you can move through New, Contacted, and Converted, not just a one-off email you have to remember to act on.

You can see the submitter's details, add a private note, and set a follow-up reminder, all without writing a line of backend code.

That is the entire setup. No server to maintain, no email provider to configure, no dashboard to build, and no spam filtering logic to write and keep tuning.

What You Get That You Would Not Have Built Yourself

This is really the heart of the argument. It is not just that a managed form backend saves you the two to four days of initial build time. It is that most people never get around to building the parts that make a form backend actually useful, because those parts are not urgent until they suddenly are.

A lead pipeline. Not just an inbox. Every submission gets a status, New, Contacted, Converted, so you know exactly what happened after someone filled out your form. This is the single most common gap in a DIY form backend, because building it means building a small CRM, not a form handler.

Automatic submission triage. Modern form backends can categorize what came in for you, flagging a genuine enquiry versus a sales pitch versus spam, and surfacing the important ones first. Building this yourself means training or wiring up a classification model on top of everything else on this list.

Permanent, searchable storage. Not a 30-day window, not a database table you have to remember to back up.

Integrations you did not have to build. Google Sheets sync, Notion sync, webhooks, CSV export. Each of these is a real integration with its own API quirks and edge cases if you build it yourself.

Spam filtering that improves without your involvement. You are not the one updating the spam patterns when a new kind of crypto spam campaign shows up.

None of this is exotic. It is just the difference between a weekend project and a product that someone maintains full-time.

Final Thoughts

Building your own form backend is a genuinely fun weekend project, and if that is what it is for you, build it. There is real value in understanding how the pieces fit together.

But if the form is infrastructure for something else, a client site, your own product's contact page, a lead capture flow for a business, it is almost never worth the time. The part that looks like the whole job, receive a POST request and send an email, is maybe 10% of what a form backend actually needs to do well. The other 90% is spam filtering, deliverability, a dashboard, storage, and a way to track what happens after someone submits, and that 90% is exactly the part that never makes it into the "quick afternoon" estimate.

Stop building your own form backend. Point your form at one instead, and spend the time you saved on the thing you were actually trying to build.

👉 Try Formgrid free at formgrid.dev. No credit card required.

Full disclosure: I built Formgrid. I wrote this as honestly as I could. If anything looks inaccurate, let me know in the comments.

Build a Restaurant Website in HTML with a Menu That Updates from Google Sheets

Allen Jones — Wed, 26 Aug 2026 16:36:00 +0000

Most restaurant websites have the same problem.

The menu is hardcoded in HTML. Every time a price changes or a dish gets added, someone has to edit the website. If the owner does not know how to code, they call their developer. The developer charges for the update. The menu is always slightly out of date.

This tutorial shows you a different approach. You
build a complete restaurant website with plain HTML.
The menu section pulls live data from a Google Sheet.
When the owner changes a price or adds a new dish, the
website updates automatically. No developer needed.
No rebuild. No redeploy.

Here is what you will build:

A complete restaurant website in plain HTML and CSS
A live menu section powered by a Google Sheet
Search and filter by category
Cart and online ordering built in
Automatic order email to the restaurant owner
Hosted on any static platform for free

The menu at the bottom of this page is a live demo.
It is pulling real data from a Google Sheet right now.

What You Will Need

Before starting, make sure you have:

A text editor (VS Code or any editor)
A Google account
A free Sheetrocket account
Basic HTML knowledge

No server. No backend. No database.

The Architecture

Here is how the whole thing works:

Restaurant owner edits Google Sheet
          |
          v
Sheetrocket reads the sheet via API
          |
          v
Widget script fetches the latest data
          |
          v
Menu renders on the HTML page automatically
          |
          v
Customer adds to cart and places order
          |
          v
Restaurant owner receives order email

The restaurant owner never touches the website.
They manage everything in a spreadsheet they already know how to use.

Step 1: Set Up Your Google Sheet

Start with your menu data. Create a new Google
Sheet with the following columns:

Name | Price | Category | Description | Image URL | Available

Here is a sample menu to get you started:

Name              | Price  | Category | Description                    | Image URL | Available
Margherita Pizza  | $12.99 | Pizza    | Classic tomato and mozzarella  | https://... | Yes
Pepperoni Pizza   | $14.99 | Pizza    | Spicy pepperoni and cheese     | https://... | Yes
Caesar Salad      | $8.99  | Salads   | Romaine, croutons, parmesan    | https://... | Yes
Grilled Chicken   | $16.99 | Mains    | Herb marinated grilled chicken | https://... | Yes
Chocolate Cake    | $6.99  | Desserts | Rich dark chocolate layers     | https://... | Yes
Lemonade          | $3.99  | Drinks   | Fresh squeezed with mint       | https://... | Yes

You can use any image URLs from Unsplash, your own
Google Drive, or any image hosting service. For
Unsplash images, add ?w=400&h=300&fit=crop to
the end of the URL to get a consistent size.

Keep the column names exactly as shown. Sheetrocket
will use them for automatic mapping.

Step 2: Create Your SheetRocket Account

Go to sheetrocket.com and
sign up for free. No credit card required.

Once you are logged in, you will see your dashboard.
This is where you create and manage your widgets,
sites, and APIs.

Step 3: Create a Menu Widget

Click Widgets in the left sidebar. Then click
Create widget.

You will see a gallery of widget templates. Click
on Menu Widget.

Give your widget a name. Something like
"Allen's Restaurant Menu" works. Click Create.

You will be taken to the widget builder. On the right side, you will see a live preview of your widget with sample data. On the left side, you have three tabs: Data, Design, and Filters.

Step 4: Connect Your Google Sheet

Click the Data tab in the left panel.

You will see two things: a data source section
and the column mapping fields below it. The column mapping fields are always visible so you can see exactly what columns your sheet needs before connecting.

Sheetrocket uses a service account to read your Google Sheet securely. You need to share your sheet with the SheetRocket service account email.

Find the service account email in the Data tab.
It looks like this:

sheetrocket@sheetrocket-app.iam.gserviceaccount.com

Copy that email address. Now go back to your
Google Sheet.

Click Share in the top right corner of your
Google Sheet. Paste the service account email
into the share field. Set the permission to
Viewer. Click Share.

Now copy the URL of your Google Sheet from your browser's address bar. It looks like this:

https://docs.google.com/spreadsheets/d/
1abc123def456/edit#gid=0

Go back to SheetRocket and paste this URL into
the Google Sheet URL field in the Data tab.
Click Connect.

Sheetrocket will read your sheet and automatically
detect your columns. You will see a success message, and the auto-mapping will pre-fill the column
mapping fields.

Review the column mapping. SheetRocket should
have matched:

Item name    →   Name
Price        →   Price
Image        →   Image URL
Category     →   Category
Description  →   Description
Available    →   Available

If any mapping is off, use the dropdown to
correct it. Click Save.

Your preview on the right side of the builder
will now show your real menu items.

Step 5: Customize the Design

Click the Design tab.

Here you can match the widget to your restaurant
branding:

Theme: Choose Light or Dark. Dark works well
for upscale restaurants. Light works for casual
cafes and family restaurants.

Accent color: Set this to your restaurant's
primary brand color. This affects badge colors
and the cart button.

Card columns: Choose 2, 3, or 4. Three columns work well for most menu layouts.

Image height: 200px to 240px works for most
food photography.

Card radius: 12px gives a modern rounded look.
0px gives a sharper, more minimal look.

The preview updates in real time as you make
changes. Take your time here to get it right before moving on.

Step 6: Set Up Category Filtering

Click the Filters tab.

Enable Show search bar. This lets customers search for specific dishes by name.

Enable Show filter dropdown. Set the filter
column to Category. This adds a dropdown
that lets customers filter by Pizza, Salads,
Mains, Desserts, and Drinks.

Enable Pagination if you have more than 12
menu items. Set items per page to 12.

Your preview will now show the search bar and
filter dropdown at the top of the menu.

Step 7: Enable Cart and Ordering

This is the part that turns a menu display into an actual ordering system.

In the Design tab, scroll down to the
Button section.

Toggle Add to cart mode on. This changes
the button on each menu card from a link to
a circular plus button. Customers tap the
plus to add items to their cart.

Set the Button color to match your
accent color.

Now scroll down further to the Cart settings
section.

Set your Order notification email. This is where SheetRocket will send an email every time a customer places an order. Use the
restaurant owner's email address.

You can also configure what fields to collect
at checkout:

Name         (required, always on)
Email        (required, always on)
Phone        toggle on or off
Address      toggle on or off
Notes        toggle on or off

For a restaurant taking delivery orders, turn on Phone and Address. For takeaway orders, just Phone is usually enough.

Toggle Send confirmation email to customer on. When a customer places an order, they will receive an automatic confirmation email with their order details.

Step 8: Copy Your Embed Code

Click the Embed tab.

You will see your embed code. It looks like this:


<div
  data-sheetrocket="your-widget-id"
  data-template="menu-widget"
  data-theme="light"
  data-columns="3">
</div>
<script
  src="https://sheetrocket.com/widget.js"
  async>
</script>

Click Copy embed code.

Step 9: Build the Restaurant Website HTML

Now you build the full restaurant website.
The menu section uses the embed code you just
copied.

Create a new file called index.html and paste
in this complete template:


<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Allen's Restaurant, Little Italy, New York</title>
  <meta name="description" content="Allen's Restaurant has been serving Little Italy since 1998. Handmade pasta, wood-fired pizza, and a table when you need one. Walk in or reserve.">
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link href="https://fonts.googleapis.com/css2?family=Karla:ital,wght@0,400;0,500;0,600;0,700;1,400&family=Playfair+Display:ital,wght@0,400;0,500;0,600;1,400;1,500&display=swap" rel="stylesheet">
  <style>
    :root {
      --paper: #F3EDE2;
      --paper-2: #E8DFD0;
      --ink: #1A1410;
      --ink-soft: #5A5248;
      --wine: #6E1C22;
      --wine-dark: #4E1318;
      --olive: #3D4A32;
      --rule: #C9BBA5;
      --on-wine: #F3EDE2;
      --font-display: "Playfair Display", Georgia, "Times New Roman", serif;
      --font-body: "Karla", system-ui, sans-serif;
      --ease: 200ms ease;
      --z-nav: 20;
      --z-menu: 30;
      --space-xs: 4px;
      --space-sm: 8px;
      --space-md: 16px;
      --space-lg: 24px;
      --space-xl: 32px;
      --space-2xl: 48px;
      --space-3xl: 80px;
      --content: 1120px;
      --gutter: clamp(1.25rem, 4vw, 2.5rem);
    }

    *, *::before, *::after {
      box-sizing: border-box;
      margin: 0;
      padding: 0;
    }

    html {
      scroll-behavior: smooth;
    }

    @media (prefers-reduced-motion: reduce) {
      html { scroll-behavior: auto; }
      *, *::before, *::after {
        animation-duration: 0.01ms !important;
        animation-iteration-count: 1 !important;
        transition-duration: 0.01ms !important;
      }
    }

    body {
      font-family: var(--font-body);
      color: var(--ink);
      background: var(--paper);
      line-height: 1.65;
      -webkit-font-smoothing: antialiased;
    }

    body::after {
      content: "";
      position: fixed;
      inset: 0;
      pointer-events: none;
      z-index: 40;
      opacity: 0.035;
      background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 200 200' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E");
    }

    img {
      max-width: 100%;
      display: block;
    }

    a, button, label, select, summary {
      cursor: pointer;
    }

    a:focus-visible,
    button:focus-visible,
    input:focus-visible,
    select:focus-visible,
    textarea:focus-visible {
      outline: 2px solid var(--wine);
      outline-offset: 3px;
    }

    .skip-link {
      position: absolute;
      left: var(--gutter);
      top: -100px;
      z-index: 50;
      background: var(--wine);
      color: var(--on-wine);
      padding: 0.75rem 1.25rem;
      font-size: 0.875rem;
      font-weight: 600;
      text-decoration: none;
    }

    .skip-link:focus {
      top: 1rem;
    }

    .wrap {
      width: min(var(--content), calc(100% - var(--gutter) * 2));
      margin-inline: auto;
    }

    #about,
    #menu,
    #reserve,
    #visit,
    #main {
      scroll-margin-top: 80px;
    }

    /* Nav */
    .site-header {
      position: sticky;
      top: 0;
      z-index: var(--z-nav);
      background: var(--paper);
      border-bottom: 1px solid var(--rule);
    }

    .nav {
      display: flex;
      align-items: center;
      justify-content: space-between;
      height: 72px;
      gap: var(--space-lg);
    }

    .nav-panel {
      margin-left: auto;
    }

    .brand {
      font-family: var(--font-display);
      font-size: 1.625rem;
      font-style: italic;
      font-weight: 500;
      color: var(--ink);
      text-decoration: none;
      line-height: 1;
    }

    .brand span {
      display: block;
      font-family: var(--font-body);
      font-style: normal;
      font-size: 0.6875rem;
      font-weight: 500;
      letter-spacing: 0.12em;
      color: var(--ink-soft);
      margin-top: 4px;
    }

    .nav-links {
      display: flex;
      align-items: center;
      gap: 2rem;
      list-style: none;
    }

    .nav-links a {
      color: var(--ink);
      text-decoration: none;
      font-size: 0.9375rem;
      font-weight: 500;
      transition: color var(--ease);
    }

    .nav-links a:hover {
      color: var(--wine);
    }

    .nav-links a.nav-reserve {
      display: inline-block;
      background: var(--wine);
      color: var(--on-wine);
      text-decoration: none;
      font-size: 0.8125rem;
      font-weight: 600;
      padding: 0.7rem 1.15rem;
      border-radius: 2px;
      transition: background var(--ease);
    }

    .nav-links a.nav-reserve:hover {
      background: var(--wine-dark);
      color: var(--on-wine);
    }

    .nav-toggle {
      display: none;
      width: 44px;
      height: 44px;
      border: 0;
      background: transparent;
      position: relative;
    }

    .nav-toggle span,
    .nav-toggle span::before,
    .nav-toggle span::after {
      display: block;
      width: 20px;
      height: 1.5px;
      background: var(--ink);
      position: absolute;
      left: 12px;
      transition: transform var(--ease), opacity var(--ease);
    }

    .nav-toggle span { top: 21px; }
    .nav-toggle span::before,
    .nav-toggle span::after {
      content: "";
      left: 0;
    }
    .nav-toggle span::before { top: -6px; }
    .nav-toggle span::after { top: 6px; }

    .nav-toggle[aria-expanded="true"] span {
      background: transparent;
    }
    .nav-toggle[aria-expanded="true"] span::before {
      top: 0;
      transform: rotate(45deg);
    }
    .nav-toggle[aria-expanded="true"] span::after {
      top: 0;
      transform: rotate(-45deg);
    }

    /* Hero */
    .hero {
      display: grid;
      grid-template-columns: minmax(0, 1fr) minmax(0, 1.15fr);
      min-height: calc(100svh - 72px);
      border-bottom: 1px solid var(--rule);
    }

    .hero-copy {
      display: flex;
      flex-direction: column;
      justify-content: center;
      padding: clamp(2.5rem, 6vw, 5rem) 2.5rem clamp(2.5rem, 5vw, 4rem) max(var(--gutter), calc((100vw - var(--content)) / 2));
    }

    .hero-copy p.lede {
      font-size: 0.875rem;
      color: var(--olive);
      font-weight: 600;
      margin-bottom: 1.25rem;
    }

    .hero h1 {
      font-family: var(--font-display);
      font-weight: 500;
      font-size: clamp(2.5rem, 5.4vw, 4.25rem);
      line-height: 1.12;
      letter-spacing: -0.02em;
      margin-bottom: 1.25rem;
    }

    .hero h1 em {
      font-style: italic;
      font-weight: 400;
    }

    .hero-copy .intro {
      font-size: 1.125rem;
      color: var(--ink-soft);
      max-width: 28rem;
      margin-bottom: 2rem;
    }

    .hero-actions {
      display: flex;
      align-items: center;
      gap: 1.5rem;
      flex-wrap: wrap;
    }

    .btn {
      display: inline-block;
      background: var(--wine);
      color: var(--on-wine);
      text-decoration: none;
      font-size: 0.9375rem;
      font-weight: 600;
      padding: 0.9rem 1.5rem;
      border: 0;
      border-radius: 2px;
      font-family: inherit;
      transition: background var(--ease);
    }

    .btn:hover {
      background: var(--wine-dark);
    }

    .text-link {
      color: var(--ink);
      font-size: 0.9375rem;
      font-weight: 600;
      text-decoration: none;
      border-bottom: 1px solid var(--ink);
      padding-bottom: 2px;
      transition: color var(--ease), border-color var(--ease);
    }

    .text-link:hover {
      color: var(--wine);
      border-color: var(--wine);
    }

    .hero-photo {
      min-height: 320px;
      overflow: hidden;
    }

    .hero-photo img {
      width: 100%;
      height: 100%;
      object-fit: cover;
      min-height: 100%;
    }

    /* About */
    .about {
      padding: var(--space-3xl) 0;
    }

    .about-grid {
      display: grid;
      grid-template-columns: 1.05fr 0.95fr;
      gap: clamp(2rem, 5vw, 4.5rem);
      align-items: center;
    }

    .about-photo {
      overflow: hidden;
    }

    .about-photo img {
      width: 100%;
      height: 100%;
      aspect-ratio: 4 / 5;
      object-fit: cover;
    }

    .about-photo figcaption {
      font-size: 0.75rem;
      color: var(--ink-soft);
      margin-top: 0.75rem;
    }

    .about h2 {
      font-family: var(--font-display);
      font-weight: 500;
      font-size: clamp(2rem, 3.5vw, 2.75rem);
      line-height: 1.2;
      margin-bottom: 1.25rem;
    }

    .about h2 em {
      font-style: italic;
      font-weight: 400;
    }

    .about p {
      color: var(--ink-soft);
      font-size: 1.0625rem;
      margin-bottom: 1rem;
    }

    .pull {
      font-family: var(--font-display);
      font-style: italic;
      font-size: 1.375rem;
      line-height: 1.45;
      color: var(--ink);
      margin: 1.75rem 0 0;
      padding-top: 1.5rem;
      border-top: 1px solid var(--rule);
    }

    /* Visit band */
    .visit {
      background: var(--wine);
      color: var(--on-wine);
      padding: 3.5rem 0;
    }

    .visit-grid {
      display: grid;
      grid-template-columns: 1.2fr repeat(3, 1fr);
      gap: 2rem;
      align-items: start;
    }

    .visit h2 {
      font-family: var(--font-display);
      font-weight: 500;
      font-size: clamp(1.75rem, 3vw, 2.25rem);
      line-height: 1.2;
    }

    .visit h2 em {
      font-style: italic;
      font-weight: 400;
    }

    .visit h3 {
      font-size: 0.75rem;
      font-weight: 600;
      letter-spacing: 0.08em;
      text-transform: uppercase;
      color: rgba(243, 237, 226, 0.65);
      margin-bottom: 0.5rem;
    }

    .visit p,
    .visit a {
      font-size: 1rem;
      color: var(--on-wine);
      text-decoration: none;
      line-height: 1.55;
    }

    .visit a:hover {
      text-decoration: underline;
    }

    /* Menu */
    .menu {
      padding: var(--space-3xl) 0;
    }

    .menu-header {
      display: grid;
      grid-template-columns: 1fr 1fr;
      gap: 2rem;
      align-items: end;
      margin-bottom: 2.5rem;
      padding-bottom: 1.5rem;
      border-bottom: 1px solid var(--rule);
    }

    .menu h2 {
      font-family: var(--font-display);
      font-weight: 500;
      font-size: clamp(2rem, 3.5vw, 2.75rem);
    }

    .menu-header p {
      color: var(--ink-soft);
      font-size: 1.0625rem;
    }

    /* Reserve */
    .reserve {
      padding: 0 0 var(--space-3xl);
    }

    .reserve-grid {
      display: grid;
      grid-template-columns: 0.85fr 1.15fr;
      gap: clamp(2rem, 5vw, 4.5rem);
      padding-top: var(--space-3xl);
      border-top: 1px solid var(--rule);
    }

    .reserve h2 {
      font-family: var(--font-display);
      font-weight: 500;
      font-size: clamp(2rem, 3.5vw, 2.75rem);
      margin-bottom: 1rem;
    }

    .reserve .lede {
      color: var(--ink-soft);
      font-size: 1.0625rem;
      margin-bottom: 1.5rem;
    }

    .reserve-note {
      font-size: 0.9375rem;
      color: var(--ink-soft);
    }

    .form-row {
      display: grid;
      grid-template-columns: 1fr 1fr;
      gap: 1.25rem;
    }

    .field {
      margin-bottom: 1.25rem;
    }

    .field label {
      display: block;
      font-size: 0.8125rem;
      font-weight: 600;
      margin-bottom: 0.4rem;
    }

    .field input,
    .field select,
    .field textarea {
      width: 100%;
      font: 400 1rem/1.4 var(--font-body);
      color: var(--ink);
      background: transparent;
      border: 0;
      border-bottom: 1px solid var(--rule);
      border-radius: 0;
      padding: 0.65rem 0;
      appearance: none;
    }

    .field select {
      background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8' viewBox='0 0 12 8'%3E%3Cpath fill='none' stroke='%231A1410' stroke-width='1.4' d='M1 1l5 5 5-5'/%3E%3C/svg%3E");
      background-repeat: no-repeat;
      background-position: right 0 center;
      padding-right: 1.5rem;
    }

    .field textarea {
      min-height: 5.5rem;
      resize: vertical;
    }

    .field input:focus,
    .field select:focus,
    .field textarea:focus {
      outline: none;
      border-bottom-color: var(--wine);
    }

    .form-status {
      display: none;
      font-family: var(--font-display);
      font-style: italic;
      font-size: 1.375rem;
      line-height: 1.45;
    }

    .form-status.is-visible {
      display: block;
    }

    form.is-sent {
      display: none;
    }

    /* Footer */
    footer {
      border-top: 1px solid var(--rule);
      padding: 1.5rem 0 2rem;
    }

    .footer-inner {
      display: flex;
      justify-content: space-between;
      align-items: baseline;
      gap: 1rem;
      flex-wrap: wrap;
    }

    .footer-inner p {
      font-size: 0.875rem;
      color: var(--ink-soft);
    }

    .footer-inner a {
      color: var(--ink);
      text-decoration: none;
    }

    .footer-inner a:hover {
      color: var(--wine);
    }

    @media (max-width: 860px) {
      .nav-toggle {
        display: block;
      }

      .nav-panel {
        display: none;
        position: absolute;
        top: 72px;
        left: 0;
        right: 0;
        z-index: var(--z-menu);
        background: var(--paper);
        border-bottom: 1px solid var(--rule);
        padding: 1rem var(--gutter) 1.5rem;
      }

      .nav-panel.is-open {
        display: block;
      }

      .nav-links {
        flex-direction: column;
        align-items: flex-start;
        gap: 1rem;
      }

      .nav-reserve {
        margin-top: 0.5rem;
      }

      .hero {
        grid-template-columns: 1fr;
        min-height: 0;
      }

      .hero-photo {
        order: -1;
        height: 46vh;
        min-height: 240px;
      }

      .hero-copy {
        max-width: none;
        padding: 2rem var(--gutter) 2.5rem;
      }

      .about-grid,
      .menu-header,
      .reserve-grid,
      .form-row {
        grid-template-columns: 1fr;
      }

      .about-photo img {
        aspect-ratio: 4 / 3;
      }

      .visit-grid {
        grid-template-columns: 1fr 1fr;
        gap: 1.75rem;
      }

      .visit-grid > :first-child {
        grid-column: 1 / -1;
      }
    }

    @media (max-width: 520px) {
      .visit-grid {
        grid-template-columns: 1fr;
      }
    }
  </style>
</head>
<body>
  <a class="skip-link" href="#main">Skip to content</a>

  <header class="site-header">
    <div class="wrap nav">
      <a href="#" class="brand">
        Allen's
        <span>Restaurant · Est. 1998</span>
      </a>

      <button class="nav-toggle" type="button" aria-expanded="false" aria-controls="nav-panel" aria-label="Open menu">
        <span></span>
      </button>

      <div class="nav-panel" id="nav-panel">
        <ul class="nav-links">
          <li><a href="#about">About</a></li>
          <li><a href="#menu">Menu</a></li>
          <li><a href="#reserve">Reservations</a></li>
          <li><a class="nav-reserve" href="#reserve">Reserve a table</a></li>
        </ul>
      </div>
    </div>
  </header>

  <main id="main">
    <section class="hero" aria-label="Introduction">
      <div class="hero-copy">
        <p class="lede">123 Pasta Lane, Little Italy</p>
        <h1>Pasta rolled this morning. <em>Sauce from yesterday.</em></h1>
        <p class="intro">
          A neighborhood kitchen for twenty-five years. Handmade pasta, wood-fired pizza, and a table when you need one.
        </p>
        <div class="hero-actions">
          <a class="btn" href="#reserve">Reserve a table</a>
          <a class="text-link" href="#menu">See the menu</a>
        </div>
      </div>
      <div class="hero-photo">
        <img
          src="https://images.unsplash.com/photo-1552566626-52f8b828add9?w=1600&q=80"
          alt="The dining room at Allen's Restaurant"
          width="1600"
          height="1200"
          fetchpriority="high"
        >
      </div>
    </section>

    <section class="about" id="about">
      <div class="wrap about-grid">
        <figure class="about-photo">
          <img
            src="https://images.unsplash.com/photo-1555396273-367ea4eb4db5?w=1200&q=80"
            alt="The dining room at Allen's Restaurant"
            width="1200"
            height="1500"
            loading="lazy"
          >
          <figcaption>The dining room on a Tuesday. Come as you are.</figcaption>
        </figure>
        <div>
          <h2>Three generations in <em>one kitchen.</em></h2>
          <p>
            Allen's Restaurant has been on Pasta Lane since 1998. Every dish is made from scratch, from recipes that started in a family kitchen outside Naples and settled here.
          </p>
          <p>
            Tomatoes come from a family farm in Campania. The cheese is from a producer two hours upstate. The pasta is rolled every morning. If we run out, we run out.
          </p>
          <p class="pull">
            “The tagliatelle is what my nonna would have made, if she had a wood oven in Little Italy.”
          </p>
        </div>
      </div>
    </section>

    <section class="visit" id="visit" aria-labelledby="visit-heading">
      <div class="wrap visit-grid">
        <h2 id="visit-heading">Walk in, or <em>call ahead.</em></h2>
        <div>
          <h3>Address</h3>
          <p>123 Pasta Lane<br>Little Italy<br>New York, NY 10013</p>
        </div>
        <div>
          <h3>Hours</h3>
          <p>Monday–Friday<br>12pm–10pm<br>Saturday–Sunday<br>11am–11pm</p>
        </div>
        <div>
          <h3>Phone</h3>
          <p><a href="tel:+12125550142">(212) 555-0142</a></p>
        </div>
      </div>
    </section>

    <section class="menu" id="menu">
      <div class="wrap">
        <div class="menu-header">
          <h2>What's cooking</h2>
          <p>Made to order. Add to your cart and we'll have it ready for pickup or delivery.</p>
        </div>
        <div
          data-sheetrocket="cmt9z2b4a0008x8sw6hrif38p"
          data-widget="menu-widget"
        ></div>
        <script src="https://sheetrocket.com/catalog-widget.js" async></script>
      </div>
    </section>

    <section class="reserve" id="reserve">
      <div class="wrap reserve-grid">
        <div>
          <h2>Reserve a table</h2>
          <p class="lede">
            Tell us when you're coming. We'll write back to confirm. Weekends fill up, so a day's notice helps.
          </p>
          <p class="reserve-note">
            For parties of eight or more, call the restaurant directly.
          </p>
        </div>

        <div>
          <p class="form-status" id="form-status" role="status"></p>
          <form id="reserve-form" action="#" method="post" novalidate>
            <div class="form-row">
              <div class="field">
                <label for="name">Name</label>
                <input id="name" name="name" type="text" autocomplete="name" required>
              </div>
              <div class="field">
                <label for="email">Email</label>
                <input id="email" name="email" type="email" autocomplete="email" required>
              </div>
            </div>
            <div class="form-row">
              <div class="field">
                <label for="date">Date</label>
                <input id="date" name="date" type="date" required>
              </div>
              <div class="field">
                <label for="time">Time</label>
                <select id="time" name="time" required>
                  <option value="">Choose a time</option>
                  <option>12:00 pm</option>
                  <option>12:30 pm</option>
                  <option>1:00 pm</option>
                  <option>1:30 pm</option>
                  <option>6:00 pm</option>
                  <option>6:30 pm</option>
                  <option>7:00 pm</option>
                  <option>7:30 pm</option>
                  <option>8:00 pm</option>
                  <option>8:30 pm</option>
                  <option>9:00 pm</option>
                </select>
              </div>
            </div>
            <div class="form-row">
              <div class="field">
                <label for="party">Party size</label>
                <select id="party" name="party" required>
                  <option value="">How many</option>
                  <option>1</option>
                  <option>2</option>
                  <option>3</option>
                  <option>4</option>
                  <option>5</option>
                  <option>6</option>
                  <option>7</option>
                </select>
              </div>
              <div class="field">
                <label for="phone">Phone</label>
                <input id="phone" name="phone" type="tel" autocomplete="tel">
              </div>
            </div>
            <div class="field">
              <label for="notes">Anything we should know?</label>
              <textarea id="notes" name="notes" placeholder="Allergies, a birthday, a quieter table…"></textarea>
            </div>
            <button class="btn" type="submit">Send request</button>
          </form>
        </div>
      </div>
    </section>
  </main>

  <footer>
    <div class="wrap footer-inner">
      <p>Allen's Restaurant · Little Italy · Est. 1998</p>
      <p><a href="tel:+12125550142">(212) 555-0142</a></p>
    </div>
  </footer>

  <script>
    (function () {
      var toggle = document.querySelector(".nav-toggle");
      var panel = document.getElementById("nav-panel");
      if (!toggle || !panel) return;

      function setOpen(open) {
        toggle.setAttribute("aria-expanded", open ? "true" : "false");
        toggle.setAttribute("aria-label", open ? "Close menu" : "Open menu");
        panel.classList.toggle("is-open", open);
      }

      toggle.addEventListener("click", function () {
        setOpen(toggle.getAttribute("aria-expanded") !== "true");
      });

      panel.querySelectorAll("a").forEach(function (link) {
        link.addEventListener("click", function () {
          setOpen(false);
        });
      });
    })();

    (function () {
      var form = document.getElementById("reserve-form");
      var status = document.getElementById("form-status");
      var dateField = document.getElementById("date");
      if (!form || !status) return;

      if (dateField) {
        var today = new Date();
        var month = String(today.getMonth() + 1).padStart(2, "0");
        var day = String(today.getDate()).padStart(2, "0");
        dateField.min = today.getFullYear() + "-" + month + "-" + day;
      }

      form.addEventListener("submit", function (event) {
        event.preventDefault();
        if (!form.checkValidity()) {
          form.reportValidity();
          return;
        }
        var submit = form.querySelector('button[type="submit"]');
        submit.disabled = true;
        submit.textContent = "Sending…";
        window.setTimeout(function () {
          form.classList.add("is-sent");
          status.textContent = "Thanks. We'll confirm your table by email shortly.";
          status.classList.add("is-visible");
        }, 400);
      });
    })();
  </script>
</body>
</html>

Replace YOUR-WIDGET-ID in the embed code with
the actual widget ID from your SheetRocket
Embed tab.

Step 10: Test the Full Website

Open index.html in your browser. You should see:

A full restaurant website with hero, about, features, menu, contact, and footer
Your live menu pulling data from your Google Sheet
Search and category filter working on the menu
Add to cart buttons on each menu card

Click the add-to-cart button on a menu item to add it
to the cart. A floating cart button will appear
at the top right of the page.

Click the floating cart button to open the cart
modal. You will see your selected items, a quantity
control, and a checkout button.

Click Checkout and fill in the order form with
a name, email, phone number, and address. Click
Place order.

Within seconds, the restaurant owner receives
an order notification email with the full
order details.

The customer also receives a confirmation email
automatically.

Step 11: Test the Live Update

This is the part that makes SheetRocket worth
using. Go back to your Google Sheet and change
a price. Update "Margherita Pizza" from $12.99
to $13.99.

Now refresh your HTML page.

The updated price appears on the menu immediately.
No website edit. No redeploy. No developer.

Add a new dish to your Google Sheet by adding
a new row at the bottom. Fill in the name, price, category, description, and image URL. Set Available to Yes.

Refresh the page. The new dish appears on the menu.

Remove a dish by deleting the row from your sheet.
Refresh the page. It is gone from the menu.

The restaurant owner can manage the entire menu
from their Google Sheet without ever touching
the website.

Step 12: Deploy the Website

Your HTML file is a static website. It can be
hosted for free on any static hosting platform.

GitHub Pages (free):

Create a new GitHub repository
Upload your index.html file
Go to Settings then Pages
Set the source to the main branch
Your site is live at yourusername.github.io/repository-name

Netlify (free):

Go to netlify.com and create a free account
Drag your index.html file onto the Netlify deploy area
Your site is live instantly at a random Netlify URL
Connect a custom domain in settings

Vercel (free):

Go to vercel.com and create a free account
Import your GitHub repository or drag your file
Your site is live at a Vercel URL
Connect a custom domain in settings

For a custom domain like mariosrestaurant.com
point your domain's DNS to your hosting provider
and add it in their dashboard.

Live Demo

The menu below is pulling live data from a
Google Sheet. Search for dishes, filter by
category, and add items to your cart to see
the full ordering flow in action.

data-sheetrocket="DEMO-WIDGET-ID"
data-template="menu-widget"
data-theme="light"
data-columns="3">

src="https://sheetrocket.com/widget.js"
async>

What the Restaurant Owner Gets

Once this is set up, the restaurant owner has
complete control over their menu without
touching the website:

Change a price:
  Edit one cell in Google Sheets
  Website updates automatically

Add a new dish:
  Add one row to the sheet
  Dish appears on the website

Remove a dish:
  Delete the row from the sheet
  Dish disappears from the website

Mark something as unavailable:
  Change Available from Yes to No
  Dish shows as unavailable
  or disappears from the menu

Add a daily special:
  Add a row with today's date
  Remove it at end of day

No login to a website builder. No calling
a developer. No waiting for someone to make the change. Just edit the spreadsheet.

Taking It Further

Add a second location:

Create a second widget for the second location
connected to a different tab in the same Google
Sheet. Embed it on a second page or on the
same page below the first.

Seasonal menus:

Create a Summer Menu tab and a Winter Menu tab
in your sheet. Switch the widget between tabs by changing one setting in SheetRocket.

Daily specials:

Add a Specials tab to your sheet. Create a
second widget connected to that tab. Embed
it above the main menu with a "Today's specials"
heading.

Multiple languages:

Duplicate your sheet tab for each language.
Create one widget per language. Show the
correct widget based on a language selector
in your HTML.

Final Thoughts

A hardcoded restaurant menu is a maintenance
problem waiting to happen. Every price change, every seasonal update, every dish removed requires a developer or someone comfortable
editing HTML.

A SheetRocket-powered menu puts control back
with the restaurant owner. They already know
how to use Google Sheets. This tutorial adds a live website connection to the spreadsheet they are already maintaining.

The website is plain HTML. It loads fast,
works on any hosting, and costs nothing to deploy. The menu updates automatically the moment the sheet is edited. Online orders arrive by email. No monthly platform fees. No complex integrations.

If you are building this for a restaurant
client, SheetRocket's Agency plan at $39/month covers unlimited restaurant sites.
Each client manages their own Google Sheet. You manage everything from one SheetRocket account.

Start free at sheetrocket.com.
No credit card required.

I am the founder of SheetRocket,
a tool that turns Google Sheets into websites,
embeddable widgets, and REST APIs. Currently
building in public from Ghana.

What Actually Makes a Software Engineer Great (It's Not the Framework You Know)

Allen Jones — Tue, 25 Aug 2026 18:50:15 +0000

Learn React. Learn a backend language. Build projects. Apply to jobs. That's the advice every developer who wants to level up hears. That advice isn't wrong, but it misses the thing that actually separates a senior engineer from someone who's been writing code for six months. It's not the framework in your resume. It's whether you understand why that framework exists in the first place, and whether you can reason about a problem well enough to pick the right tool instead of the familiar one.

Here are the three things that actually move the needle.

1. Understand the "Why," Not Just the "How"

If you're learning to code today, the common advice is "learn React." Fair enough, React is popular and in demand. But if you don't understand why React had to exist, how frontend development worked before it, and what problem it was solving, you're going to hit a ceiling.

A quick example: before async/await existed, asynchronous JavaScript was written with nested callbacks, and once you had a few dependent async operations in a row, that nesting turned into what everyone just called callback hell. Promises came along to flatten that out, and async/await came after to make asynchronous code read almost like synchronous code. If you only learn async/await as "the syntax you use for async stuff," you'll be lost the moment you open an older codebase full of .then() chains or raw callbacks. Knowing what problem it replaced is what lets you actually read and work in code that predates it.

This matters because tools get chosen for reasons, and those reasons change depending on the problem. A senior engineer doesn't reach for React (or Rails, or Django, or whatever is trending) by default. They look at what the project actually needs to solve, now and as it grows, and pick technology based on that.

A Concrete Example: Node.js vs Python

This "understand the why" idea gets a lot more concrete when you compare Node.js and Python, because the two languages handle concurrency in fundamentally different ways, and that difference decides what each one is actually good at.

Node.js runs on a single thread with a non-blocking event loop. When a request comes in that needs to read a file, hit a database, or call another API, Node doesn't block that thread waiting for the response. It hands the operation off (to libuv under the hood), keeps handling other requests, and comes back to yours when the data is ready.

// Node.js: this doesn't block the event loop
app.get('/user/:id', async (req, res) => {
  const user = await db.query('SELECT * FROM users WHERE id = ?', [req.params.id]);
  res.json(user);
});

This makes Node excellent at I/O bound workloads: REST APIs, real-time apps (chat, live notifications via WebSockets), streaming services, and anything where a request spends most of its time waiting on the network or disk rather than doing heavy computation. A single Node process can juggle thousands of concurrent connections because it isn't burning CPU cycles or a full thread stack per connection.

Where Node struggles is CPU-bound work. Because everything runs on that one thread, a heavy synchronous computation (image processing, video encoding, complex encryption, large in-memory data crunching) blocks the event loop entirely. Every other request waiting on that same process just freezes until the computation finishes.

// This blocks every other request until it finishes
app.get('/process', (req, res) => {
  const result = heavyImageProcessing(req.body.image); // blocks the event loop
  res.json(result);
});

Node does have worker_threads and child_process to push CPU-heavy work off the main thread, but that's a workaround you have to reach for deliberately; it's not the default execution model.

Python's story is almost the opposite. Python has something called the GIL, the Global Interpreter Lock. It means that even if you spin up multiple threads in a single Python process, only one thread can execute Python bytecode at a time. So naive multi-threading in Python does not give you true parallelism for CPU-bound work. Adding more threads to a CPU-heavy Python task usually doesn't make it faster, because they're all waiting their turn for the same lock.

This is why Python isn't the first choice for something like a high-concurrency real-time API server written from scratch, at least not without help. Pure multi-threaded Python doesn't scale CPU work the way you'd expect.

But this is also where it gets interesting, because Python is still the dominant language in data science and machine learning, and that's not a contradiction. Two things make it work:

I/O bound work still benefits from Python's concurrency tools. The GIL is released while a thread is waiting on I/O (network calls, file reads), so Python's threading module or asyncio (which mirrors Node's event loop model) still works well for I/O heavy workloads like web scraping or calling multiple APIs concurrently.
** CPU-heavy libraries do their real work outside the GIL.** Libraries like NumPy, pandas, and PyTorch are built on C, C++, or CUDA under the hood. When you call a NumPy operation on a large array, Python hands the actual number crunching to compiled code that releases the GIL and can run in parallel or on a GPU. Python itself is just the orchestration layer; the heavy lifting happens outside the interpreter entirely.

For true CPU-bound parallelism in pure Python (not delegated to a C extension), you reach for multiprocessing, which spins up separate processes, each with its own interpreter and its own GIL, and splits the work across CPU cores. It works, but it's heavier than threading because each process has its own memory space.

Where each one fits:

	Good fit	Weak fit
Node.js	APIs and microservices with high concurrent I/O, real-time apps, streaming, chat backends, thin services with light CPU work	Heavy synchronous computation, video/image processing, CPU-heavy encryption, ML model training
Python	Data science, machine learning, scientific computing, scripting and automation, I/O bound work via asyncio, backends where the ecosystem (FastAPI, Django) fits	Raw CPU-bound parallelism using plain threads, extremely high-concurrency real-time servers without async tooling

Neither language is "better." They were built with different priorities, and picking between them for a project means understanding what kind of work that project actually does, not just which one you're more comfortable with. That's the same lesson as the React example, just at the language level instead of the framework level.

Why This Matters More With AI Tools

This "understand the why" skill matters even more now that AI coding agents can write most of the code for you. There's a real difference between telling an AI agent "add authentication to this app" and being able to tell it whether to use sessions or JWTs, how long tokens should live, whether refresh tokens belong in an httpOnly cookie or local storage, and what happens to existing logged-in users when the auth flow changes.

The AI is doing the typing. The decisions still have to come from you. If your AI agent can make a technical decision without you being able to explain why it was the right one, that's worth noticing, because it means the reasoning skill isn't being built, only the code is.

2. Product Engineering: Go Beyond Writing Code

The role of a software engineer is shifting. It used to be enough to be handed a spec and implement it well. Increasingly, engineers are expected to be part of figuring out what should be built in the first place.

That means being comfortable with things that used to sit entirely with product managers: talking to users to understand the actual problem they're facing, translating that into a roadmap or a set of tickets, tying the work back to a business goal, and collaborating with product managers and designers on how the solution should work before a single line of code gets written.

Once that planning is done, handing the implementation over to an AI agent (or just writing it yourself) becomes the easy part. The hard, valuable part is everything that happens before that: understanding the problem well enough to know what "done" actually looks like.

3. System Design: Know What's Underneath the Platform

A lot of developers can push code to a managed hosting platform and have it live in minutes without ever thinking about what's happening behind that button. That's completely fine for shipping fast, but it becomes a real gap the moment you're handed infrastructure that nobody has already wired up for you.

Picture a different scenario: you're told your application needs to handle ten times its current traffic with no downtime. Would you know whether the fix is adding more app servers behind a load balancer, moving to a bigger single server, or introducing a caching layer so the database stops doing repeated work? If terms like reverse proxy, connection pooling, or cache invalidation feel fuzzy, that's less about any one tool and more about a gap in system design fundamentals.

The fundamentals worth understanding here:

The difference between horizontal scaling (more machines) and vertical scaling (bigger machines), and when each makes sense
What a load balancer and a reverse proxy actually do, and how requests get routed across multiple app servers
Private networking and secure communication between services
Database security, connection pooling, and access patterns at scale
Managing infrastructure through code and version control versus clicking through a cloud dashboard by hand

Using a managed hosting platform because it's fast and convenient is a completely reasonable choice. The problem is only when it's the only thing you know how to do, because the moment a project needs something that platform doesn't offer, you're stuck without the fundamentals to build it yourself.

Putting It Together

None of these three things (understanding the fundamentals behind your tools, thinking like a product engineer, and understanding system design) show up on a "learn React in 30 days" course outline. They're slower to build and harder to measure. But they're also the actual difference between an engineer who can be handed any problem and figure it out, and one who can only work within the exact stack and constraints they were taught.

If you're early in your career, you don't need to master all three at once. Start by picking apart one tool or framework you already use every day and asking why it exists, what problem it solved, and what the alternative would have looked like without it. That habit, repeated across enough tools, is what builds the kind of judgment that AI can't replace for you.

The N+1 Query Problem: Why Your API Might Be Making 101 Database Queries Instead of 2

Allen Jones — Tue, 25 Aug 2026 15:55:47 +0000

If your API feels fast in development but becomes painfully slow in production as your data grows, there's a good chance you're looking at the N+1 query problem. It's one of the most common backend performance issues, and the frustrating part is that the code usually looks completely fine at first glance.

The Setup

Say you have two tables: customers and orders. Each order belongs to a customer through a foreign key.

CREATE TABLE customers (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255)
);

CREATE TABLE orders (
  id SERIAL PRIMARY KEY,
  customer_id INTEGER REFERENCES customers(id),
  total NUMERIC(10, 2)
);

Here's what that relationship looks like. Each row in orders points back to exactly one row in customers through customer_id, while a single customer can have many orders pointing at them. That's a classic one to many relationship.

erDiagram
    customers ||--o{ orders : "has many"
    customers {
        int id PK
        varchar name
    }
    orders {
        int id PK
        int customer_id FK
        numeric total
    }

You can also picture it as two flat tables with the foreign key drawing the line between them:

customers                      orders
+----+---------+               +----+-------------+--------+
| id | name    |               | id | customer_id | total  |
+----+---------+               +----+-------------+--------+
| 1  | Sarah   |     <---------| 1  | 1           | 42.00  |
| 2  | James   |     <---+     | 2  | 1           | 15.50  |
| 3  | Emily   |     <-+ \-----| 3  | 2           | 99.99  |
+----+---------+       \-------| 4  | 3           | 27.30  |
                                +----+-------------+--------+

Every arrow is orders.customer_id referencing customers.id. That's the foreign key. It's what makes it possible to reconstruct "this customer, with these orders" without storing the order data twice.

Now say you want to return every customer along with all the orders they've placed. A common first pass looks something like this (pseudocode, but it maps closely to a naive Prisma or ActiveRecord setup):

const customers = await db.query('SELECT * FROM customers');

for (const customer of customers) {
  customer.orders = await db.query(
    'SELECT * FROM orders WHERE customer_id = ?',
    [customer.id]
  );
}

Why It's Called N+1

This looks reasonable. You get all the customers, then loop through and grab each one's orders. But look at what's actually hitting the database:

One query to fetch all customers
One additional query per customer to fetch that customer's orders

If you have 100 customers, that's 1 query for the customers plus 100 queries for their orders: 101 total queries. Hence "N+1," where N is the number of rows from the first query.

sequenceDiagram
    participant App
    participant DB

    App->>DB: SELECT * FROM customers
    DB-->>App: 100 customers

    loop for each of the 100 customers
        App->>DB: SELECT * FROM orders WHERE customer_id = ?
        DB-->>App: orders for that customer
    end

    Note over App,DB: Total: 1 + 100 = 101 queries

This scales linearly with your data, and not in a good way. At 100 customers, 101 queries might not even show up as a bottleneck. At 100,000 customers, that's 100,001 queries per request, and your database (and your server) will not thank you for it. If this endpoint is something like an admin dashboard or a customer list page that gets hit often, that cost repeats on every single request.

The Fix: A Single SQL JOIN

Instead of fetching customers and orders separately, you can pull both in one query using a JOIN:

SELECT
  customers.id,
  customers.name,
  orders.id AS order_id,
  orders.total
FROM customers
LEFT JOIN orders ON orders.customer_id = customers.id;

This returns every customer paired with each of their orders in a single result set, one round trip to the database instead of N+1.

sequenceDiagram
    participant App
    participant DB

    App->>DB: SELECT customers.*, orders.* FROM customers LEFT JOIN orders ON orders.customer_id = customers.id
    DB-->>App: all customers with their orders, in one result set

    Note over App,DB: Total: 1 query, regardless of customer count

Your application code then just needs to group the flat rows back into a nested structure (customers with an orders array), which is a cheap in-memory operation compared to hundreds of network round trips to the database.

How Different Frameworks Solve This

Every major ORM has a built-in way to do this join for you, they just name it differently:

Framework	Feature name	Example
Django	`select_related` / `prefetch_related`	`Customer.objects.prefetch_related('orders')`
Laravel (Eloquent)	Eager loading	`Customer::with('orders')->get()`
Prisma	`include`	`prisma.customer.findMany({ include: { orders: true } })`
Rails (ActiveRecord)	Eager loading	`Customer.includes(:orders)`

Under the hood, they're all doing roughly the same thing: either issuing a single JOIN query, or batching the "get related records" step into one WHERE customer_id IN (...) query instead of N separate ones. Either approach collapses N+1 queries down to 1 or 2.

How to Catch This in Your Own Code

The tricky part about N+1 is that the code reads fine. The problem only shows up when you look at what's actually hitting the database. A few ways to catch it:

Turn on query logging in development and count how many queries a single request generates. If that number scales with the size of your dataset, that's the smell. A "get all customers" endpoint that fires 1 query with 5 test customers and 51 queries with 50 customers is the tell.
Most ORMs have a debug or profiling mode (Prisma's query logging, Laravel Debugbar, Django Debug Toolbar) that will show you the exact query count per request.
Load test with realistic data volumes, not 5 rows in a dev database. N+1 is invisible at small scale and brutal at large scale.

It Gets Worse With Nested Relationships

The two table example is the simplest case, but N+1 compounds fast once you add another level of relationships. Say each order also has line items:

const customers = await db.query('SELECT * FROM customers');

for (const customer of customers) {
  customer.orders = await db.query(
    'SELECT * FROM orders WHERE customer_id = ?',
    [customer.id]
  );

  for (const order of customer.orders) {
    order.items = await db.query(
      'SELECT * FROM order_items WHERE order_id = ?',
      [order.id]
    );
  }
}

Now you're not just paying N+1, you're paying N (customers) plus M (orders per customer) queries, nested inside each other. With 100 customers averaging 5 orders each, that's 1 query for customers, 100 queries for orders, and 500 more queries for order items: 601 queries for what should be 3.

This is exactly the shape of bug that shows up in GraphQL resolvers too. A resolver for orders that runs a query per parent customer, and a resolver for items that runs a query per parent order, will happily reproduce N+1 at every level of the graph unless something batches those calls. This is why libraries like dataloader exist in the GraphQL/Node ecosystem: they collect all the individual "get orders for customer X" calls that fire within a single tick, merge them into one WHERE customer_id IN (1, 2, 3, ...) query, and hand each caller back its slice of the result.

A Rough Sense of the Cost

Query count is only part of the story, latency per query matters too. If a single query takes even 2ms round trip (a reasonable number for a local or same region database), the difference looks like this as your customer table grows:

Customers	N+1 queries	Approx. time at 2ms/query	Join queries	Approx. time
100	101	~200ms	1	~2ms
1,000	1,001	~2s	1	~2ms
10,000	10,001	~20s	1	~2ms
100,000	100,001	~200s	1	~2ms

Those numbers are simplified (real databases pipeline and cache some of this), but the trend is the real point: N+1 turns your response time into a function of your data size, while a JOIN keeps it roughly constant regardless of how many customers you have. For something like an order history page or a checkout flow, that's the difference between a page that loads instantly and one that times out under real traffic.

Don't Forget the Index

A JOIN only stays fast if the foreign key column is indexed. Without an index on orders.customer_id, the database has to scan the entire orders table for every customer it's joining against, which can turn your one query fix into a slow one query fix on large tables.

CREATE INDEX idx_orders_customer_id ON orders(customer_id);

Most ORMs create this index automatically when you define a foreign key relationship, but it's worth checking on tables that were set up by hand or migrated from another system, since a missing index here is a common reason a JOIN based fix still feels slow.

Takeaway

N+1 is one of those bugs that doesn't look like a bug. The code is readable, it passes tests, and it works fine with a handful of records. It's only when your data grows that the query count explodes and starts dragging down response times. The fix is almost always the same: replace the loop of individual queries with a single JOIN or your ORM's eager loading feature, and let the database do the work it's actually good at.

What an idempotency key actually does

Allen Jones — Fri, 21 Aug 2026 00:34:23 +0000

A client sends a transfer request. The server debits the sender, credits the receiver, commits, and starts writing the response. The connection drops half a millisecond before the client reads it. The client, seeing no response, does the only reasonable thing a retry policy knows how to do: sends the same request again.

The server has no idea any of that happened. It just sees a second, perfectly well-formed request to move money. So it does it again.

Client                          Server
  |                                |
  |----- POST /transfers -------->|
  |                                | debit sender
  |                                | credit receiver
  |                                | commit
  |        X  (connection drops)  |
  |                                |
  | (timeout, no response seen)   |
  |                                |
  |----- POST /transfers -------->|  <-- identical request
  |                                | debit sender  (again)
  |                                | credit receiver  (again)
  |                                | commit
  |<---------- 200 OK -------------|

That is the whole problem. Not a rare one either; it's the default behavior of almost every HTTP client library the moment you add a timeout and a retry. The client did nothing wrong. It genuinely cannot tell the difference between "the server never got my request" and "the server got it, handled it, and I just never heard back."

Why "just check the balance first" doesn't work

The instinct is to guard the transfer with a check: does the sender have enough balance, is the receiver valid, and so on. None of that helps here. The retried request is not invalid. It's a completely legitimate transfer request that happens to be a duplicate of one that already succeeded. Every validation check passes, twice.

You also can't fix this by making the operation "fast enough" that retries become rare. Networks time out for reasons that have nothing to do with your server's speed: a client-side timeout fires, a proxy in the middle drops the connection, a mobile client loses signal for two seconds. The request already fully executed on your server. The client just never found out.

The fix is a key, not a check

An idempotency key is a value the client generates once per logical operation, before it ever calls the endpoint, and sends on every attempt of that same operation, retries included.

const idempotencyKey = crypto.randomUUID();

await fetch('/api/transfers', {
  method: 'POST',
  headers: { 'Idempotency-Key': idempotencyKey },
  body: JSON.stringify({ fromAccount, toAccount, amount }),
});

If the request fails or times out, the client retries with the same key. Not a new one. The key represents "this transfer," not "this HTTP request."

Client                          Server
  |                                |
  | key = "6f2a-...-91"           |
  |----- POST /transfers -------->|
  |     Idempotency-Key: 6f2a     | key seen? no
  |                                | debit sender
  |                                | credit receiver
  |                                | store result under 6f2a
  |        X  (connection drops)  |
  |                                |
  |----- POST /transfers -------->|  <-- same key, same body
  |     Idempotency-Key: 6f2a     | key seen? yes
  |                                | skip transfer logic entirely
  |<---------- 200 OK -------------|  return the stored result

On the server, before doing anything with money, check whether that key has been seen before:

CREATE TABLE idempotency_keys (
  key text PRIMARY KEY,
  request_hash text NOT NULL,
  response_status int,
  response_body jsonb,
  created_at timestamptz DEFAULT now()
);

async function handleTransfer(key: string, payload: TransferRequest) {
  const existing = await db.query(
    'SELECT * FROM idempotency_keys WHERE key = $1',
    [key]
  );

  if (existing.rows.length > 0) {
    return existing.rows[0].response_body;
  }

  const result = await executeTransfer(payload);

  await db.query(
    `INSERT INTO idempotency_keys (key, request_hash, response_status, response_body)
     VALUES ($1, $2, $3, $4)`,
    [key, hashPayload(payload), 200, result]
  );

  return result;
}

Second attempt with the same key finds the stored row and returns the original result. It never touches the transfer logic again. The money moves exactly once, no matter how many times the network makes the client ask.

Same key, different payload, is a bug, not a replay

There's a failure mode this simple version misses. What if the same key shows up with a different amount, because of a bug on the client, or someone reusing a key by accident? A naive lookup would happily return the stored response from a completely different transfer and call it correct.

That's what request_hash in the table is for. On the second request, before trusting the cached response, compare the hash of the incoming payload against what was stored the first time:

const incomingHash = hashPayload(payload);

if (existing.rows.length > 0) {
  if (existing.rows[0].request_hash !== incomingHash) {
    throw new ConflictError('Idempotency key reused with a different request');
  }
  return existing.rows[0].response_body;
}

A mismatch here should be a hard error, not a silent overwrite in either direction. It means either the client has a bug generating keys, or something worse. Either way, replaying a different transfer under an old key is exactly the kind of thing idempotency exists to prevent, so the check has to be as strict as the thing it's protecting.

Three states, not two

The lookup above only really distinguishes "never seen" from "seen and done." There's a third state hiding in between: seen, but still running. It shows up the moment two attempts overlap in time instead of arriving one after another.

              INSERT reserves the key
                        |
                        v
        +---------------------------+
        |          PENDING          |   response_body IS NULL
        |  (transfer in progress)   |
        +---------------------------+
                        |
          executeTransfer() finishes
                        |
                        v
        +---------------------------+
        |         COMPLETED         |   response_body populated
        |   (safe to replay freely) |
        +---------------------------+

        A different payload hash arriving
        against an existing key, in either
        state above, is neither of these.
        It is a CONFLICT, and should be
        rejected outright.

A lookup that only checks "does a row exist" can't tell a PENDING row from a COMPLETED one. Reading a PENDING row's response_body gets you NULL, not "please wait." The read path has to check which state it landed in and behave differently for each.

The race no one thinks about until it bites

Everything above assumes the two attempts arrive one after another. They don't have to. A client with an aggressive retry policy can fire the retry before the first attempt has finished, especially if the timeout it's reacting to was on the client side, not because the server was actually slow. Now two requests with the same key are running concurrently, and both can pass the "have I seen this key" check before either has written a row.

Time  Request A                    Request B
----  --------------------------   --------------------------
 t0   check key "6f2a"  -> none
 t1                                check key "6f2a"  -> none
 t2   begin transfer
 t3                                begin transfer      <-- !!
 t4   debit sender
 t5                                debit sender         <-- both proceed
 t6   credit receiver
 t7                                credit receiver
 t8   INSERT key "6f2a"  -> ok
 t9                                INSERT key "6f2a"  -> UNIQUE VIOLATION

Both proceed to execute the transfer. The unique constraint on key will stop the second INSERT from succeeding, but by then the second request may have already moved money, because the transfer logic and the idempotency check aren't happening atomically. The constraint catches the write collision after the damage, not before it.

The fix is to reserve the key before doing the work, not after:

async function handleTransfer(key: string, payload: TransferRequest) {
  const incomingHash = hashPayload(payload);

  try {
    await db.query(
      `INSERT INTO idempotency_keys (key, request_hash, response_status, response_body)
       VALUES ($1, $2, NULL, NULL)`,
      [key, incomingHash]
    );
  } catch (err) {
    if (isUniqueViolation(err)) {
      return await waitForCompletedResult(key, incomingHash);
    }
    throw err;
  }

  const result = await executeTransfer(payload);

  await db.query(
    `UPDATE idempotency_keys
     SET response_status = 200, response_body = $2
     WHERE key = $1`,
    [key, result]
  );

  return result;
}

Re-run the same race with the reservation moved first:

Time  Request A                    Request B
----  --------------------------   --------------------------
 t0   INSERT key "6f2a"  -> ok
 t1                                INSERT key "6f2a"  -> UNIQUE VIOLATION
 t2   begin transfer
 t3                                wait for row to complete
 t4   debit sender
 t5   credit receiver
 t6   UPDATE key "6f2a" -> done
 t7                                read completed row -> return result

Only one request ever touches the transfer logic. The other one blocks on the database's own uniqueness guarantee, which is enforced by Postgres itself, not by application code hoping nothing runs in between two steps. Whether "wait" means polling the row every hundred milliseconds or something fancier depends on how much concurrency you're actually expecting. For a personal project, polling is a perfectly honest starting point.

Idempotency is not a transaction

Worth being precise about this, because the two get blurred together.

+-----------------------------------------------------+
|                 One HTTP request                    |
|                                                       |
|   +-----------------------------------------------+ |
|   |         Database transaction (ACID)            | |
|   |                                                 | |
|   |   debit sender  -->  credit receiver  -->  ok   | |
|   |   (both happen, or neither does)               | |
|   +-----------------------------------------------+ |
|                                                       |
+-----------------------------------------------------+
                          ^
                          |
        Idempotency key wraps the OUTSIDE of this box,
        making it safe to ask for the whole box again.

A database transaction makes a single operation atomic: the debit and the credit inside executeTransfer either both happen or neither does. Idempotency is a different guarantee, layered on top: it makes repeating the same request from the outside safe, regardless of how many times it's repeated. You need both. The transaction protects the money during one execution. The idempotency key protects the money across retries of that execution.

Keys don't live forever

One thing I glossed over: the idempotency_keys table grows with every request, forever, if nothing ever removes old rows. Most systems only need a key to stay valid for as long as a client might plausibly still be retrying an hour, maybe twenty-four, not indefinitely.

DELETE FROM idempotency_keys
WHERE created_at < now() - interval '24 hours';

Run on a schedule, this keeps the table from becoming a second, ever-growing ledger sitting next to the real one. It also means a key can safely be reused after that window closes, which matters if client code ever generates keys from something less random than a UUID, a timestamp plus a user ID, say.

What I check now

Before I add a new "money moving" endpoint anywhere, I check:

Does the client generate the key before the first attempt, and reuse it on every retry, never a fresh key per retry?
Is the key reserved with a unique constraint before the operation runs, not just checked and then trusted?
Does a key collision with a different payload hash fail loudly, instead of silently returning the wrong stored result?
Does the read path distinguish pending from completed, instead of treating "row exists" as one single state?
Am I storing the actual response, so a retry gets back the same answer the original call would have given, not just a generic "already done"?
Do old keys expire, so the table isn't a permanent second ledger?

The transfer logic was never the hard part. Making it safe to ask twice was.

Embeddings are just arrays. Retrieval is the work.

Allen Jones — Thu, 20 Aug 2026 14:56:45 +0000

I delayed actually using embeddings because the word sounds like a research paper. It is not. An embedding is a list of numbers that stands in for a piece of text. Same length every time. Nearby lists mean nearby meaning, if the model is any good.

That is the whole trick. The rest is plumbing.

What I hold in my head

Take a sentence. Send it through a model. Get back 1536 floats (or 384, or 768; the number is a property of the model, not a law of nature). Store that array next to the original text.

At query time, embed the question the same way. Compare arrays. Return the texts whose arrays are closest.

No search index is required to understand this. A nested loop over ten chunks in a test file is enough:

function cosineSimilarity(a: number[], b: number[]): number {
  if (a.length !== b.length) {
    throw new Error('Vector length mismatch');
  }

  let dot = 0;
  let magA = 0;
  let magB = 0;

  for (let i = 0; i < a.length; i += 1) {
    dot += a[i] * b[i];
    magA += a[i] * a[i];
    magB += b[i] * b[i];
  }

  return dot / (Math.sqrt(magA) * Math.sqrt(magB));
}

When I could explain that function without looking it up, the libraries stopped feeling like magic.

Two arrays from two different models are not comparable

This one cost me an afternoon. I had a batch of chunks embedded with one model, then switched providers mid experiment and re-embedded only the new chunks with a different model. Same dimension count, coincidentally. The code ran. No errors. The similarity scores were just quietly wrong, every query returning a confident, meaningless top match.

Two embeddings are only comparable if the same model produced both. Not the same dimension count, the same model, ideally the same version of it. A 1536 length array from one model and a 1536 length array from another are just two arrays that happen to be the same size. They do not share a coordinate system. Cosine similarity between them is a number, but it is not a meaningful one.

The fix was boring: store the model name and version next to every embedding, and refuse to compare across a mismatch instead of letting it fail silently.

type EmbeddingRecord = {
  vector: number[];
  model: string;
  createdAt: string;
};

If I change embedding models later, I re-embed everything. There is no partial migration where old and new vectors coexist in the same comparison. That single row of metadata is what makes that decision obvious the next time, instead of a debugging session.

Chunking is the product decision

The array is only as useful as the text you fed the model. I first embedded whole markdown files. Retrieval returned "the right document" and the wrong paragraph. Then I split on headings, then on overlapping windows of ~400 tokens.

There is no universal chunk size. There is only: what question will a user ask, and how much surrounding context does an answer need?

I am treating chunking as a product decision, not a preprocessing detail. The table schema should remember that:

type Chunk = {
  id: string;
  docId: string;
  body: string;
  headingPath: string[];
  embedding: number[];
};

headingPath has already saved me once, when two chunks were numerically close and only the section title told me which one belonged in the answer.

Looking at what actually gets retrieved

Before I let anything call an LLM, I wrote a script that does nothing but print the top five matches for a hardcoded question, with their scores, and nothing else:

async function debugRetrieve(question: string, k = 5) {
  const queryVector = await embed(question);
  const results = chunks
    .map((chunk) => ({
      chunk,
      score: cosineSimilarity(queryVector, chunk.embedding),
    }))
    .sort((a, b) => b.score - a.score)
    .slice(0, k);

  for (const { chunk, score } of results) {
    console.log(score.toFixed(4), chunk.headingPath.join(' > '), '\n', chunk.body.slice(0, 120));
  }
}

Running this against a dozen questions I already knew the answers to caught more bugs than any amount of staring at the ingestion code did. It's how I found a chunking script that was silently producing empty headingPath arrays for every chunk in one document, because the regex assumed headings started at the beginning of a line and one file used a different line ending. Every chunk still embedded fine. The score still returned a number. Nothing errored. It just made every match from that document indistinguishable from every other match from that document, and I would not have noticed without reading the raw output.

An LLM sitting on top of bad retrieval will still write a fluent, confident sentence. That is exactly why I don't trust it to tell me the retrieval is broken. I have to look at the arrays and the text myself, before the LLM ever gets involved.

Brute force works until it doesn't

The nested loop above is O(n), it checks every stored vector against the query vector, every time. For ten chunks that's instant. For a few hundred, still instant. I am not optimizing this yet, on purpose.

The reason people reach for pgvector's ivfflat or hnsw indexes, or a dedicated vector database, is that brute force stops being instant somewhere in the tens or hundreds of thousands of rows, depending on hardware. Those indexes trade a small amount of accuracy (they're approximate nearest neighbor, not exact) for a large amount of speed at that scale.

I don't have that problem yet. Adding an index before you need one just adds a second thing that can be subtly wrong, on top of the chunking and the model mismatch and everything else already in the pipeline. The honest brute force loop is also the easiest thing to verify by hand, which matters more right now than the query taking two milliseconds instead of two hundred.

The embedding call is a network call

Easy to forget, since it's wrapped in a function named something friendly like embed(). It's an HTTP request to someone else's server. It has latency, it has a rate limit, and it costs a fraction of a cent every time you make it.

Re-embedding the same chunk twice because a script re-ran is a real way to burn through a rate limit for no reason. The fix is a hash of the chunk's text, stored alongside the embedding:

type Chunk = {
  id: string;
  docId: string;
  body: string;
  headingPath: string[];
  embedding: number[];
  contentHash: string;
};

Before embedding a chunk, hash its body and compare against what's stored. Same hash, skip the call. Different hash, the text changed, re-embed it. It's a caching problem wearing an AI costume.

What I am not doing yet

I am not fine-tuning. I am not swapping models every afternoon. I am not building a vector database product. I am not indexing for scale I don't have. I am trying to get one retrieval path honest: same model in, same model out, scores I can explain, chunks a human could have picked, and a debug script I actually run before trusting the output.

The arrays are the easy part. Making the surrounding system tell the truth is the work.