This guide covers ten areas of Lambda excellence for .NET, each derived from real-world production patterns and common failure modes. It assumes you are comfortable with the basics of Lambda and the AWS .NET SDK, and focuses on the why behind each practice as much as the how.

Runtime & Deployment Model

Use .NET 10 (or Latest LTS) on arm64

What it is: AWS Graviton2 processors power arm64 Lambda functions. They offer better performance-per-dollar for most workloads, and AWS charges approximately 20% less per GB-second compared to x86.

Why it matters: For a high-traffic function with 500ms average duration at 512 MB memory, switching from x86 to arm64 can save over $15/month per million daily invocations with zero code changes.

# template.yaml
Globals:
  Function:
    Runtime: dotnet10
    Architectures:
      - arm64
    MemorySize: 512

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: MyFunction::MyFunction.Function::FunctionHandler
      CodeUri: src/MyFunction/

Minimize Deployment Package Size

What it is: The deployment package is the ZIP artifact containing your compiled application and its dependencies, uploaded to Lambda via S3. Its size directly affects how long Lambda takes to extract and load your code during a cold start.

Why it matters: Lambda extracts and initializes your deployment package on every cold start. A 50 MB package takes significantly longer to initialize than a 5 MB one. Smaller packages also reduce S3 storage costs and deployment time.

Use Native AOT Compilation

What it is: Ahead-of-Time (AOT) compilation converts your .NET code directly into a native binary at build time, eliminating the Just-In-Time (JIT) compiler that normally runs when a .NET application starts. For Lambda, this means the initialization phase — the most expensive part of a cold start — is dramatically faster.

Why it matters: Lambda bills in 1ms increments. Cold starts are fully billed duration. On a JIT-based .NET function, initialization can take 400–1200ms depending on the number of loaded assemblies and SDK clients. With Native AOT, this drops to 30–80ms.

Use Lambda SnapStart (if not using AOT)

What it is: SnapStart takes a snapshot of the initialized execution environment after the Init phase completes and caches it. Subsequent cold starts restore from the snapshot instead of re-running initialization, reducing cold start latency by up to 90%.

Why it matters: If you have an existing JIT-based .NET function that you cannot easily migrate to AOT (e.g., it uses libraries incompatible with trimming), SnapStart delivers most of the cold start benefit without a code rewrite.

Memory & CPU Sizing

Profile with AWS Lambda Power Tuning

What it is: The AWS Lambda Power Tuning tool is an open-source Step Functions state machine that runs your function at multiple memory configurations (e.g., 128 MB, 256 MB, 512 MB, 1024 MB, 1769 MB, 3008 MB) and returns a cost and performance graph showing the optimal setting.

Why it matters: The relationship between memory and cost is not linear because CPU allocation scales with memory. A function that runs in 1000ms at 256 MB might run in 200ms at 1024 MB, making the higher-memory option cheaper despite a higher per-ms rate.

Don't Under-Allocate Memory

What it is: Lambda allocates CPU proportionally to memory. Setting memory too low starves your function of CPU, which can make it run slower and cost more despite the lower per-GB-second rate.

Why it matters: A .NET function with heavy computation (JSON parsing, data transformation, LINQ operations) starved of CPU at 256 MB may run 4–8x slower than at 1769 MB, making it cost more despite the lower RAM pricing.

Set Memory Based on Actual Measurements

What it is: Every Lambda invocation emits a REPORT log line containing the actual peak memory used. This measured value is the correct baseline for sizing your memory allocation, rather than guessing.

Why it matters: Setting memory allocation to peak measured usage plus 15% headroom prevents out-of-memory errors while avoiding wasteful over-provisioning. Both extremes cost money: OOM errors cause failed invocations and retries; excessive headroom means you pay for memory you never use.

REPORT RequestId: abc123  Duration: 245.12 ms  Billed Duration: 246 ms
Memory Size: 512 MB  Max Memory Used: 178 MB

Set your memory allocation to peakMB * 1.15 (15% headroom above peak measured usage).

Cold Start Optimization

Move Heavy Initialization Outside the Handler

What it is: In Lambda, code that runs at class construction or in static initializers executes only once per execution environment lifecycle — during the Init phase — not on every invocation. By moving expensive setup (SDK client construction, config loading, connection establishment) outside the handler method, you ensure it runs once and is reused.

Why it matters: Lambda reuses execution environments across invocations and freezes them between calls, preserving static state. Initialization that runs during the Init phase is billed as part of the cold start, which occurs infrequently. The same code inside the handler runs on every invocation, making every call slower and more expensive.

Use Provisioned Concurrency for Latency-Critical Paths

What it is: Provisioned Concurrency pre-initializes a specified number of execution environments, keeping them warm and ready to handle requests with no cold start. The environments are fully initialized — your static constructors have already run.

Why it matters: For synchronous, user-facing functions (e.g., API endpoints powering a mobile app), cold start latency can directly degrade user experience. Provisioned Concurrency eliminates cold starts entirely for those pre-warmed environments. It should not be used for async workers, background jobs, or event-processing functions, where latency is not user-visible and the added cost is unjustified.

Lazy-Load Non-Critical Dependencies

What it is: For dependencies only needed in specific code paths, use Lazy<T> to defer their initialization until the first time that code path is actually executed, rather than initializing them unconditionally at startup.

Why it matters: Eagerly initializing every dependency at startup contributes to cold start duration and memory usage, even for code paths that may never be invoked in a given execution environment. Lazy loading ensures you only pay the initialization cost for dependencies that are actually used.

Avoid Heavy DI Containers in the Hot Path

What it is: Reflection-based dependency injection frameworks (Microsoft.Extensions.DependencyInjection with assembly scanning, Autofac, etc.) perform extensive reflection during container construction. This conflicts directly with both Native AOT (which requires all types to be known at compile time) and cold start minimization goals.

Why it matters: Reflection-based DI scanning can add hundreds of milliseconds to your Init phase and is incompatible with Native AOT trimming. Preferred alternatives are manual wiring (fastest, recommended for simple functions) and source-generated DI (for more complex compositions).

Execution & Compute Efficiency

Use async/await Throughout — Avoid .Result and .Wait()

What it is: async/await enables non-blocking I/O in .NET — when a function awaits a network call, the thread is released to do other work. .Result and .Wait() are synchronous blocking calls that hold the thread until the operation completes.

Why it matters: Lambda bills for wall-clock time, not CPU time. A thread blocked on .Result or .Wait() holds the execution environment hostage while waiting for I/O, consuming billed duration even though it is doing nothing. It can also cause deadlocks in certain synchronization contexts.

Reuse HttpClient and AWS SDK Clients Across Invocations

What it is: HttpClient and AWS SDK service clients (e.g., AmazonDynamoDBClient) are designed to be long-lived and thread-safe. They should be created once as static fields and reused across invocations, not constructed per-request.

Why it matters: Each new HttpClient() creates a new socket pool. Creating one per invocation rapidly exhausts available ports (the default ephemeral port range is ~30,000), causing socket exhaustion under load — a notoriously difficult production bug to diagnose. AWS SDK clients hold connection pools internally; re-creating them per invocation defeats connection reuse and adds DNS resolution overhead on every call.

Set Appropriate Timeout

What it is: Lambda's timeout setting defines the maximum duration an invocation is allowed to run before it is forcibly terminated. It is configurable from 1 second to 15 minutes per function.

Why it matters: Lambda's default timeout for new functions is 3 seconds — too short for most real workloads. But setting it to the maximum (15 minutes) "just in case" means a function that hangs due to a slow downstream service will bill the full 15 minutes before being terminated. Calculate your timeout based on measured performance:

Timeout = (p99 measured duration) × 2 + network overhead margin

For example, if your function normally completes in 800ms and has a p99 of 1.2 seconds, set timeout to 3–5 seconds, not 15 minutes.

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    Timeout: 10    # Seconds — not 900 (15 min)

Use System.Text.Json over Newtonsoft.Json

What it is: System.Text.Json (STJ) is the built-in .NET JSON library introduced in .NET Core 3.1. It is allocation-friendly, supports Span<T> for zero-copy parsing, and is fully compatible with Native AOT via source generation. Newtonsoft.Json is the older, widely used third-party library that predates STJ.

Why it matters: Newtonsoft.Json relies on reflection, is incompatible with Native AOT, adds ~500 KB to your deployment package, and is measurably slower for typical Lambda payloads. STJ delivers better throughput, lower memory pressure, and AOT compatibility with no external dependency.

Avoid Boxing and Unnecessary Allocations in Hot Paths

What it is: Boxing occurs when a value type (e.g., int, struct) is implicitly converted to object, causing a heap allocation. Unnecessary allocations include creating objects, strings, arrays, or closures that are immediately discarded after a single use.

Why it matters: Lambda functions that process thousands of events per second generate enormous GC pressure if they produce many short-lived heap objects per invocation. GC pauses directly extend billed duration and increase tail latency.

Concurrency & Scaling

Set Reserved Concurrency to Avoid Noisy-Neighbor Throttling

What it is: Reserved concurrency is a per-function setting that both guarantees a minimum concurrency allocation for a function and caps its maximum concurrency. By default, all Lambda functions in an AWS account share a regional concurrency pool (default: 1,000 concurrent executions).

Why it matters: Without reserved concurrency, a single function experiencing a traffic spike can consume the entire regional pool, throttling completely unrelated functions in the same account. Reserved concurrency prevents this by isolating a function's allocation from the shared pool.

Configure SQS Batch Size and Batch Window

What it is: When Lambda polls an SQS queue, it can retrieve and process multiple messages in a single invocation (a batch). BatchSize controls the maximum number of messages per invocation. MaximumBatchingWindowInSeconds controls how long Lambda waits to fill the batch before invoking. ReportBatchItemFailures tells Lambda which specific messages in a batch failed, so only those are retried.

Why it matters: Larger batches mean fewer Lambda invocations, which directly reduces cost. Without ReportBatchItemFailures, if one message in a batch of 100 fails, all 100 are returned to the queue and reprocessed — a 100x amplification of failed work.

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Events:
      SQSTrigger:
        Type: SQS
        Properties:
          Queue: !GetAtt MyQueue.Arn
          BatchSize: 100
          MaximumBatchingWindowInSeconds: 5
          FunctionResponseTypes:
            - ReportBatchItemFailures

Message visibility timeout must be greater than max function execution time.

Use Event Filtering on SQS/DynamoDB/Kinesis Triggers

What it is: Lambda event source filtering lets you define a filter pattern at the AWS service level. Messages that don't match the filter are discarded by the service before they ever invoke your function.

Why it matters: You are not billed for filtered-out events, and your function doesn't need to contain logic to discard irrelevant messages. This reduces invocation count, cost, and code complexity.

Events:
  SQSTrigger:
    Type: SQS
    Properties:
      Queue: !GetAtt MyQueue.Arn
      FilterCriteria:
        Filters:
          - Pattern: '{"body": {"eventType": ["ORDER_PLACED"]}}'

Tune Maximum Concurrency on Event Source Mappings

What it is: The ScalingConfig.MaximumConcurrency property on an event source mapping caps how many concurrent Lambda executions can be processing from that specific source simultaneously, independent of the function's overall reserved concurrency.

Why it matters: Without this limit, a large SQS queue backlog can scale Lambda to hundreds of concurrent executions simultaneously. This can overwhelm downstream databases or APIs not designed for that level of parallelism, causing cascading failures.

Events:
  SQSTrigger:
    Type: SQS
    Properties:
      Queue: !GetAtt MyQueue.Arn
      BatchSize: 10
      ScalingConfig:
        MaximumConcurrency: 10

Networking & Integrations

Avoid VPC Unless Strictly Necessary

What it is: Placing a Lambda function inside a VPC attaches an Elastic Network Interface (ENI) to the function's execution environment, giving it access to private VPC resources. This is required for accessing services that have no public endpoint, such as RDS or ElastiCache.

Why it matters: ENI attachment adds 100–500ms of cold start latency and introduces capacity constraints in subnets. Lambda functions outside a VPC still run in AWS-managed, isolated infrastructure with no public inbound access — the security benefit of VPC placement is often overstated. Services like DynamoDB, S3, SQS, and SNS are all accessible without a VPC (or via VPC endpoints if the function is already in one).

Use VPC Endpoints for AWS Services

What it is: VPC Endpoints (Gateway endpoints for S3/DynamoDB, Interface endpoints for most other services) route traffic between your Lambda function and AWS services privately within the AWS network, bypassing the public internet and NAT Gateway.

Why it matters: Without VPC endpoints, traffic from a VPC-based Lambda to AWS services routes through a NAT Gateway, which charges $0.045 per GB of data processed. For a high-throughput function reading large S3 objects, this adds up quickly. VPC endpoints eliminate the NAT Gateway data charge (Interface endpoints have a small hourly fee, but it is offset by avoided NAT costs above roughly 10 GB/month).

Enable Connection Pooling and Keep-Alive for HTTP

What it is: HTTP connection pooling reuses established TCP connections across multiple requests rather than opening a new connection for each one. In Lambda, SocketsHttpHandler manages this pool, and it persists across invocations as long as the execution environment stays warm.

Why it matters: Without connection reuse, each Lambda invocation (or each HTTP call within it) incurs TCP handshake and TLS negotiation overhead. Tuning pool settings prevents stale connections from causing errors while keeping connections alive long enough to benefit from reuse.

private static readonly HttpClient HttpClient = new HttpClient(new SocketsHttpHandler
{
    PooledConnectionLifetime = TimeSpan.FromMinutes(15),
    PooledConnectionIdleTimeout = TimeSpan.FromMinutes(2),
    MaxConnectionsPerServer = 50,
    UseCookies = false
})
{
    Timeout = TimeSpan.FromSeconds(10)
};

Configure AWS SDK Retry and Timeout

What it is: The AWS SDK has a built-in retry policy that automatically retries failed requests with exponential backoff. The default configuration retries up to 3 times. Both the retry count and per-attempt timeout can be configured on each SDK client.

Why it matters: For a Lambda function with a 5-second timeout calling a struggling DynamoDB table, the SDK's default aggressive retry policy may consume the entire timeout window retrying, billing you for the full duration and still returning an error. Setting explicit retry limits and per-call timeouts gives you control over this behavior.

Observability & Cost Visibility

Enable Lambda Insights

What it is: Lambda Insights is an enhanced CloudWatch monitoring feature that captures per-invocation metrics including memory used, CPU time, init duration, and network I/O. It is enabled by attaching the managed LambdaInsightsExtension Lambda layer to your function.

Why it matters: The default Lambda CloudWatch metrics (invocations, duration, errors) don't surface resource-level detail like memory pressure or CPU utilization. Lambda Insights fills that gap, making it possible to identify memory leaks, CPU-bound invocations, and slow init phases without adding custom instrumentation.

Cost note: Lambda Insights charges for custom CloudWatch metrics (~$0.30 per metric per month) and additional log data. For high-traffic functions, filter what you emit.

Use Structured Logging with Log Level Filtering

What it is: Structured logging emits log entries as JSON objects with consistent fields (timestamp, level, message, correlation IDs, etc.) rather than plain text strings. Log level filtering suppresses verbose logs (e.g., Debug, Trace) in production while keeping Warning and Error output.

Why it matters: Plain string logs are hard to query at scale. Structured JSON logs can be filtered and aggregated efficiently with CloudWatch Logs Insights. Log level control reduces log volume and CloudWatch ingestion costs in production.

To accomplish this easily, use Powertools for AWS Lambda (.NET).

Set CloudWatch Log Retention Policy

What it is: Each Lambda function automatically gets a CloudWatch Log Group. The default retention policy is "Never Expire," meaning logs accumulate indefinitely. You can configure a retention period (e.g., 14 days) via CloudFormation or the console.

Why it matters: CloudWatch Logs storage is billed at $0.03/GB. With "Never Expire," logs from high-volume functions accumulate indefinitely, and the bill grows silently. Explicitly setting a retention period caps storage costs and keeps log groups manageable.

Resources:
  MyFunctionLogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: !Sub "/aws/lambda/${MyFunction}"
      RetentionInDays: 14

Use X-Ray or OpenTelemetry for Distributed Tracing

What it is: AWS X-Ray is a distributed tracing service that instruments calls across Lambda invocations, AWS service calls (DynamoDB, S3, SQS), and outbound HTTP requests, producing service maps and per-segment latency breakdowns. OpenTelemetry is the vendor-neutral alternative that can export to X-Ray, Jaeger, or other backends.

Why it matters: Standard CloudWatch metrics tell you that a function is slow; distributed tracing tells you which downstream call is responsible. This is invaluable for identifying the specific DynamoDB query or external API call causing p99 latency spikes.

Globals:
  Function:
    Tracing: Active

To accomplish this easily, use Powertools for AWS Lambda (.NET).

Tag All Lambda Functions with Cost Allocation Tags

What it is: AWS resource tags are key-value pairs attached to resources. Cost Allocation Tags are tags you activate in the Billing console, after which AWS Cost Explorer can group and filter Lambda spending by those tag values.

Why it matters: Without consistent tagging, Lambda costs in a shared account appear as a single line item, making it impossible to attribute spending to specific teams, features, or environments. Tags enable per-team or per-service cost accountability.

Globals:
  Function:
    Tags:
      Team: payments
      Environment: production
      Service: order-processing

Architecture & Design

Keep Functions Single-Purpose

What it is: A single-purpose Lambda function handles one specific operation (e.g., process an order event, resize an image, send a notification) rather than branching across multiple unrelated operations based on input type.

Why it matters: A function that branches heavily based on input type ends up sized for its most demanding branch, wasting memory and compute for all other branches. Single-purpose functions are easier to size, tune independently, monitor, and debug.

Consider Lambda URLs vs API Gateway

What it is: Lambda Function URLs are built-in HTTPS endpoints directly on a Lambda function, requiring no additional AWS service. API Gateway is a fully managed service that sits in front of Lambda and adds features like request validation, authorizers, usage plans, WAF integration, and stage variables.

Why it matters: For simple HTTP endpoints that don't need API Gateway features, Lambda Function URLs eliminate the $1.00 per million request charge that HTTP API Gateway adds, reducing cost to Lambda invocation charges only. The right choice depends on whether you need the additional API Gateway capabilities.

Use Step Functions for Orchestration over Chained Lambdas

What it is: AWS Step Functions is a serverless orchestration service that coordinates multi-step workflows. The alternative — chaining Lambda functions by having one function synchronously invoke another and wait for its response — keeps the calling function's execution environment alive and billing during the entire wait.

Why it matters: Synchronously chaining Lambda functions doubles or triples your Lambda bill because the caller is billed for the full wait duration. Step Functions handles orchestration at the service level; your Lambda functions execute independently and are only billed for their own compute time.

Security

Apply Least-Privilege IAM Execution Roles

What it is: Every Lambda function runs under an IAM execution role. This role defines exactly which AWS API calls the function is permitted to make. Many teams default to broad managed policies like AmazonDynamoDBFullAccess or even AdministratorAccess during development and never revisit them.

Why it matters: If your function is compromised through a vulnerability in your code or a dependency, the attacker inherits every permission in that execution role. A function that can only call dynamodb:GetItem on one specific table does far less damage than one with write access to all tables in the account.

Never Store Secrets in Environment Variables or Source Code

What it is: Lambda environment variables are convenient but are stored in plaintext in the function configuration, visible to anyone with lambda:GetFunctionConfiguration or lambda:GetFunction IAM access. The correct alternative is AWS Secrets Manager or AWS Systems Manager Parameter Store (SecureString), where secrets are fetched at runtime and access is controlled via IAM.

Why it matters: Database passwords, API keys, and signing secrets in environment variables or source code have been the root cause of numerous high-profile cloud breaches. The AWS Shared Responsibility Model makes secret storage entirely your responsibility.

Enable AWS WAF on API Gateway or CloudFront

What it is: AWS WAF (Web Application Firewall) inspects HTTP requests before they reach your Lambda function, blocking common attack patterns (SQL injection, XSS, path traversal), known malicious IP ranges, and volumetric abuse. It is attached to API Gateway, CloudFront, or an Application Load Balancer.

Why it matters: Without WAF, a Lambda function exposed via API Gateway is reachable by anyone on the internet. Even a well-validated function can be overwhelmed by a flood of requests (costing money in Lambda invocations) or hit with sophisticated payloads designed to exploit dependencies.

Use Resource-Based Policies to Restrict Who Can Invoke

What it is: A Lambda resource policy (also called a function policy) defines which AWS principals — accounts, services, or IAM roles — are allowed to call lambda:InvokeFunction on your function. It is separate from the function's execution role, which controls what the function can do.

Why it matters: Without a restrictive resource policy, an API Gateway misconfiguration or an accidental public URL can expose your function to arbitrary invocation from the internet, leading to unexpected charges and potential data exposure.

Restrict Lambda Function URL Auth

What it is: Lambda Function URLs support two authentication modes: AuthType: NONE (publicly invocable by anyone with the URL) and AuthType: AWS_IAM (requires a valid AWS Signature Version 4 signed request). The NONE mode is occasionally used for public webhooks but is a security risk for most production functions.

Why it matters: AuthType: NONE means the URL is publicly accessible with no authentication. Anyone who discovers or guesses the URL can invoke your function at your expense and potentially exfiltrate or corrupt data. Use AWS_IAM for any function that is not intentionally public.

Operations

Configure Dead Letter Queues on Async Invocations

What it is: A Dead Letter Queue (DLQ) is an SQS queue or SNS topic configured to receive events that Lambda failed to process after exhausting its retry attempts. For asynchronous invocations (from SNS, S3 events, EventBridge, or direct async InvokeFunction calls), Lambda retries failed invocations twice by default before discarding the event.

Why it matters: Without a DLQ, a transient downstream failure (a throttled DynamoDB table, a network timeout) can cause permanent, silent data loss with no alert and no recovery path. Silent event loss is one of the hardest production bugs to detect.

Resources:
  MyFunctionDLQ:
    Type: AWS::SQS::Queue
    Properties:
      QueueName: my-function-dlq
      MessageRetentionPeriod: 1209600   # 14 days in seconds

  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      Runtime: dotnet10
      DeadLetterQueue:
        Type: SQS
        TargetArn: !GetAtt MyFunctionDLQ.Arn
      EventInvokeConfig:
        MaximumRetryAttempts: 2
        MaximumEventAgeInSeconds: 3600

Always alarm on DLQ depth so a backlog is immediately visible.

Use Lambda Destinations for Async Success and Failure Routing

What it is: Lambda Destinations are a more flexible evolution of DLQs. They let you route both successful and failed async invocations to an SQS queue, SNS topic, EventBridge bus, or another Lambda function, with the full original event and function response or error details included in the routed payload.

Why it matters: DLQs receive only the original input event on failure. Destinations receive the original event plus the function response or error details for both successes and failures, making post-processing, alerting, and conditional routing significantly richer. They also enable success-path routing, which DLQs cannot do.

Alarm on Errors, Throttles, and Duration Breaches

What it is: Lambda publishes several CloudWatch metrics out of the box: Errors, Throttles, Duration, ConcurrentExecutions, and IteratorAge (for stream-based triggers). CloudWatch Alarms can monitor these metrics and trigger notifications or automated actions when thresholds are breached.

Why it matters: None of these metrics have alarms by default — you must create them explicitly. Without alarms, a function silently failing 10% of invocations, hitting account-level concurrency limits, or processing events that are hours behind will go undetected until a user or downstream system reports a problem.

ErrorRateAlarm:
  Type: AWS::CloudWatch::Alarm
  Properties:
    AlarmName: !Sub "${MyFunction}-ErrorRate"
    Metrics:
      - Id: errors
        MetricStat:
          Metric:
            Namespace: AWS/Lambda
            MetricName: Errors
            Dimensions: [{ Name: FunctionName, Value: !Ref MyFunction }]
          Period: 60
          Stat: Sum
      - Id: invocations
        MetricStat:
          Metric:
            Namespace: AWS/Lambda
            MetricName: Invocations
            Dimensions: [{ Name: FunctionName, Value: !Ref MyFunction }]
          Period: 60
          Stat: Sum
      - Id: errorRate
        Expression: "errors / invocations * 100"
        Label: ErrorRate
    ComparisonOperator: GreaterThanThreshold
    Threshold: 1
    EvaluationPeriods: 2
    TreatMissingData: notBreaching
    AlarmActions: [!Ref OpsAlertTopic]

ThrottleAlarm:
  Type: AWS::CloudWatch::Alarm
  Properties:
    AlarmName: !Sub "${MyFunction}-Throttles"
    MetricName: Throttles
    Namespace: AWS/Lambda
    Dimensions: [{ Name: FunctionName, Value: !Ref MyFunction }]
    Statistic: Sum
    Period: 300
    EvaluationPeriods: 1
    Threshold: 1
    ComparisonOperator: GreaterThanOrEqualToThreshold
    AlarmActions: [!Ref OpsAlertTopic]

DurationAlarm:
  Type: AWS::CloudWatch::Alarm
  Properties:
    AlarmName: !Sub "${MyFunction}-DurationP99"
    MetricName: Duration
    Namespace: AWS/Lambda
    Dimensions: [{ Name: FunctionName, Value: !Ref MyFunction }]
    ExtendedStatistic: p99
    Period: 300
    EvaluationPeriods: 3
    Threshold: 8000   # 8 seconds if timeout is 10 seconds
    ComparisonOperator: GreaterThanThreshold
    AlarmActions: [!Ref OpsAlertTopic]

Use Lambda Aliases and Traffic Shifting for Safe Deployments

What it is: Lambda aliases are named pointers to specific function versions (e.g., live → version 12). Traffic shifting, configured through AWS CodeDeploy, allows you to route a percentage of invocations to a new version while the majority still goes to the current stable version — a serverless canary or linear deployment.

Why it matters: Deploying a new function version directly to 100% of traffic has no rollback path faster than re-deploying the previous version, which takes 30–90 seconds. With canary or linear deployments, CodeDeploy monitors your CloudWatch alarms and automatically rolls back to the previous version the moment an alarm fires — often within 60 seconds of a bad deployment.

Quick Reference

Must = required for any production function regardless of workload. Optional = strongly advisable but context-dependent — the "When to apply" column clarifies when it becomes effectively mandatory.

The current checklist is a starting point. Adapt it to your team's context, add items that reflect your specific compliance requirements or architectural patterns, and remove items that genuinely do not apply to your workload. The goal is not a perfect score — it is a shared, team-maintained definition of what a production-ready Lambda function looks like for your organization. Thanks, and happy coding

• SNS (Simple Notification Service)

• SQS (Simple Queue Service)

• S3 (Simple Storage Service)

• DynamoDB

• Lambda

• IAM, EC2, Kinesis, Secrets Manager, and many more

The key insight is that Moto Server speaks the exact same HTTP protocol as real AWS. Our application code — including the AWS SDK — does not need any modification to switch between Moto Server and real AWS. The only change is the endpoint URL. Moto Server does not require real credentials, and it does not validate them. However, AWS SDKs still expect credentials to exist, so we usually must provide dummy credentials in environment variables or config files.

Why Use Moto Server?

The Problem with Testing Against Real AWS

Testing cloud-native applications presents a persistent challenge: real AWS services are external, stateful, and cost money. Running integration tests against live infrastructure leads to:

• Slow feedback loops: Network latency adds seconds to every test case.

• Flaky behavior: Network timeouts, throttling, and eventual consistency make tests non-deterministic.

• Cloud cost: High-frequency test pipelines can generate unexpected AWS bills.

• Environment coupling: Developers share the same dev/staging account, causing test data collisions.

• No offline development: We cannot work on a plane or in an environment with no internet.

How Moto Server Solves These Problems

• Slow feedback loops: Runs locally; no network round-trips to AWS.

• Flaky behavior: Deterministic in-memory state; no eventual consistency.

• Cloud cost: Completely free; runs as a local Docker container.

• Environment coupling: Each developer (or CI run) spins up their own isolated instance.

• No offline development: Runs entirely offline.

Moto Server vs. LocalStack

A natural question is: why not use LocalStack? Both tools simulate AWS locally, but they differ in philosophy and scope.

• LocalStack is a commercial product (with a free tier) that runs each AWS service in a dedicated process and focuses on maximum fidelity, including networking emulation.

• Moto Server is a pure open-source, community-driven project. It runs all services in a single process and is particularly strong for SNS, SQS, S3, and DynamoDB.

For most integration testing scenarios — especially message-broker flows with SNS and SQS — Moto Server is lightweight, zero-configuration, and entirely sufficient.

Running Moto Server Locally with Docker

Moto Server ships as an official Docker image. Spinning it up takes one command.

docker run --rm -d --name moto-server -p 5000:5000 motoserver/moto:latest

What each flag does:

• --rm: Removes the container when it stops, keeping our environment clean.

• -d: Runs in detached (background) mode.

• --name moto-server: Gives the container a predictable name for referencing later.

• -p 5000:5000: Maps port 5000 on our host machine to port 5000 inside the container. Moto Server listens on port 5000 by default.

Once started, the server is immediately ready at http://localhost:5000. To verify the server is running navigate to http://localhost:5000/moto-api/, we should see a dashboard. Moto Server also exposes a reset endpoint that is useful between test runs http://localhost:5000/moto-api/reset (POST).

Using Moto Server

Let's create a couple of applications—a message producer and its consumer—to see Moto Server in action.

Setting Up AWS Resources with the AWS CLI

Before our applications can publish or consume messages, the AWS resources (SNS topic, SQS queue, and the subscription linking them) must exist. In a real project, we would employ Infrastructure as Code tools like Terraform, CDK, or CloudFormation. However, for local development with Moto Server, the AWS CLI offers the quickest setup, though it can also be integrated with these tools.

No special profile configuration is needed. Moto Server does not validate credentials — it accepts any value the CLI sends. The only flag that matters is --endpoint-url, which redirects the request from the real AWS endpoint to our local Moto instance. As long as the CLI has some credentials available (from environment variables, our default profile, or any other source), the request will be signed and Moto will accept it. All commands in this section use only --endpoint-url http://localhost:5000.

Creating the SNS Topic

aws sns create-topic --name my-topic --endpoint-url http://localhost:5000

Creating the SQS Queue

aws sqs create-queue --queue-name my-queue --endpoint-url http://localhost:5000

Subscribing the SQS Queue to the SNS Topic

The SNS subscription requires the SQS queue's ARN, not its URL. Retrieve it with:

aws sqs get-queue-attributes --queue-url <QUEUE_URL> --attribute-names QueueArn --endpoint-url http://localhost:5000

This is the step that wires the two services together. When a message is published to the SNS topic, SNS will automatically deliver it to all subscribers — in this case, the SQS queue.

aws sns subscribe --topic-arn <TOPIC_ARN> --protocol sqs --notification-endpoint <QUEUE_ARN> --endpoint-url http://localhost:5000

Building the SNS Producer

The producer application is a minimal .NET Web API that accepts an HTTP request and publishes an event to the SNS topic.

dotnet new webapi -n SnsProducer
cd SnsProducer
dotnet add package AWSSDK.SimpleNotificationService
dotnet add package AWSSDK.Extensions.NETCore.Setup

Why these packages:

• AWSSDK.SimpleNotificationService: The AWS SDK for the SNS service.

• AWSSDK.Extensions.NETCore.Setup: Provides GetAWSOptions() and AddAWSService<T>(), the idiomatic integration between the AWS SDK and .NET's dependency injection container.

The SDK's GetAWSOptions() extension reads from the reserved AWS section of appsettings.json. This is the only place that needs to change between environments — the application code is identical across all of them.

{
  "AWS": {
    "Region": "us-east-1",
    "ServiceURL": "http://localhost:5000",
  }
}

Why two keys in the AWS section?

• Region: the logical AWS region. The SDK uses this to construct ARNs and to select the correct real AWS endpoint under normal circumstances.

• ServiceURL: overrides the endpoint entirely, redirecting all requests to Moto Server instead of real AWS. When this is set, Region no longer drives endpoint selection — it is used purely for ARN construction.

In rare cases we could need to setup the AuthenticationRegion key. This key tells the SDK which region to embed in the AWS Signature Version 4 request signature. Both Region and AuthenticationRegion must match the region used when creating our AWS resources. Open the Program.cs file and replace the content with:

// Program.cs
using System.Text.Json;
using Amazon.SimpleNotificationService;
using Amazon.SimpleNotificationService.Model;

var builder = WebApplication.CreateBuilder(args);

// GetAWSOptions() reads the "AWS" section from appsettings.json.
// Credentials are resolved from environment variables by the SDK automatically.
builder.Services.AddDefaultAWSOptions(builder.Configuration.GetAWSOptions());

// Registers a fully configured, singleton IAmazonSimpleNotificationService.
builder.Services.AddAWSService<IAmazonSimpleNotificationService>();

var app = builder.Build();

const string TopicArn = "<TOPIC_ARN>";

var jsonOptions = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
    WriteIndented = false
};

app.MapPost("/api/events", async (
    IAmazonSimpleNotificationService sns,
    ILogger<Program> logger,
    CancellationToken cancellationToken) =>
{
    var eventId = Guid.NewGuid();

    var orderEvent = new MyEvent(
        EventId: eventId,
        Message: $"New event {eventId}",
        CreatedAt: DateTimeOffset.UtcNow
    );

    // Serialize the event to JSON. The message body is always a string in SNS.
    var messageBody = JsonSerializer.Serialize(orderEvent, jsonOptions);

    var publishRequest = new PublishRequest
    {
        TopicArn = TopicArn,
        Message = messageBody,
        // MessageGroupId and MessageDeduplicationId are required for FIFO topics.
        // For standard topics, Message Attributes are useful for filtering.
        MessageAttributes = new Dictionary<string, MessageAttributeValue>
        {
            ["EventType"] = new MessageAttributeValue
            {
                DataType = "String",
                StringValue = nameof(MyEvent)
            },
            ["Version"] = new MessageAttributeValue
            {
                DataType = "String",
                StringValue = "1.0"
            }
        }
    };

    logger.LogInformation(
        "Publishing {EventType} for order {EventId} to topic {TopicArn}",
        nameof(MyEvent), eventId, TopicArn);

    try
    {
        var response = await sns.PublishAsync(publishRequest, cancellationToken);

        logger.LogInformation(
            "Published {EventType} successfully. MessageId: {MessageId}",
            nameof(MyEvent), response.MessageId);
    }
    catch (Exception ex)
    {
        logger.LogError(ex,
            "Failed to publish {EventType} for order {EventId}",
            nameof(MyEvent), eventId);
        throw;
    }

    return Results.Ok();
});

app.Run();

record MyEvent(
    Guid EventId,
    string Message,
    DateTimeOffset CreatedAt
);

Building the SQS Consumer

The consumer is a .NET Worker Service — a long-running background process that continuously polls the SQS queue and processes incoming messages.

dotnet new worker -n SqsConsumer
cd SqsConsumer
dotnet add package AWSSDK.SQS
dotnet add package AWSSDK.Extensions.NETCore.Setup

Just like the producer, the entire consumer lives in a single file. Open the Program.cs file and replace the content with:

// Program.cs
using System.Text.Json;
using System.Text.Json.Serialization;
using Amazon.SQS;
using Amazon.SQS.Model;

var builder = Host.CreateApplicationBuilder(args);

// GetAWSOptions() reads the "AWS" section from appsettings.json.
// Credentials are resolved from environment variables by the SDK automatically.
builder.Services.AddDefaultAWSOptions(builder.Configuration.GetAWSOptions());

// Registers a fully configured, singleton IAmazonSQS.
builder.Services.AddAWSService<IAmazonSQS>();

builder.Services.AddHostedService<SqsPollingWorker>();

var host = builder.Build();
host.Run();

public class SqsPollingWorker(IAmazonSQS sqs, ILogger<SqsPollingWorker> logger)
    : BackgroundService
{
    // QueueUrl is hardcoded here for simplicity in this example.
    // In a production codebase, read it from configuration or AWS Parameter Store.
    private const string QueueUrl =
        "<QUEUE_URL>";

    // Long polling: holds the connection open for up to 20 seconds.
    // This drastically reduces empty responses and cuts API call costs.
    private const int WaitTimeSeconds = 20;

    // Retrieve up to 10 messages per poll request (the SQS maximum).
    private const int MaxNumberOfMessages = 10;

    // VisibilityTimeout hides the message from other consumers while processing.
    // If processing fails and the message is not deleted, it reappears after this timeout.
    // Set it comfortably above the maximum expected processing time.
    private const int VisibilityTimeoutSeconds = 30;

    private static readonly JsonSerializerOptions JsonOptions = new()
    {
        PropertyNameCaseInsensitive = true
    };

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        logger.LogInformation("SQS consumer started. Polling queue: {QueueUrl}", QueueUrl);

        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                await PollAndProcessAsync(stoppingToken);
            }
            catch (OperationCanceledException)
            {
                // Expected when the host is shutting down. Break cleanly.
                break;
            }
            catch (Exception ex)
            {
                // Log unexpected errors but keep the loop running.
                // Without this, a single transient error would kill the worker.
                logger.LogError(ex, "Unexpected error in SQS polling loop. Retrying in 5 seconds.");
                await Task.Delay(TimeSpan.FromSeconds(5), stoppingToken);
            }
        }

        logger.LogInformation("SQS consumer stopped.");
    }

    private async Task PollAndProcessAsync(CancellationToken cancellationToken)
    {
        var receiveRequest = new ReceiveMessageRequest
        {
            QueueUrl              = QueueUrl,
            WaitTimeSeconds       = WaitTimeSeconds,
            MaxNumberOfMessages   = MaxNumberOfMessages,
            VisibilityTimeout     = VisibilityTimeoutSeconds,
            MessageSystemAttributeNames        = ["All"],
            MessageAttributeNames = ["All"]
        };

        var response = await sqs.ReceiveMessageAsync(receiveRequest, cancellationToken);

        if (response.Messages == null)
            return; // No messages — long poll timed out. Loop again immediately.

        if (response.Messages.Count == 0)
            return; // No messages — long poll timed out. Loop again immediately.

        logger.LogInformation("Received {Count} message(s) from SQS.", response.Messages.Count);

        // Process each message independently so a failure on one does not
        // prevent the others from being handled.
        await Task.WhenAll(response.Messages
            .Select(msg => ProcessMessageAsync(msg, cancellationToken)));
    }

    private async Task ProcessMessageAsync(Message sqsMessage, CancellationToken cancellationToken)
    {
        try
        {
            // Step 1: Unwrap the SNS envelope.
            // When SNS delivers to SQS it wraps the payload in a notification envelope.
            // The actual event lives inside envelope.Message as a JSON string.
            var envelope = JsonSerializer.Deserialize<SnsEnvelope>(sqsMessage.Body, JsonOptions);

            if (envelope is null || envelope.Type != "Notification")
            {
                logger.LogWarning(
                    "Received non-notification message type '{Type}'. Deleting.",
                    envelope?.Type ?? "unknown");
                // Delete malformed or unexpected messages to avoid infinite retries.
                await DeleteMessageAsync(sqsMessage, cancellationToken);
                return;
            }

            var eventType = envelope.MessageAttributes?.GetValueOrDefault("EventType")?.Value;

            logger.LogDebug(
                "Processing SNS notification. MessageId={MessageId}, EventType={EventType}",
                envelope.MessageId, eventType ?? "unknown");

            // Step 2: Deserialize the inner payload.
            var myEvent = JsonSerializer.Deserialize<MyEvent>(envelope.Message, JsonOptions);

            if (myEvent is null)
            {
                logger.LogError(
                    "Failed to deserialize MyEvent from message {MessageId}. Body: {Body}",
                    sqsMessage.MessageId, envelope.Message);
                // Do NOT delete — let the visibility timeout expire so the message
                // can be retried or moved to a dead-letter queue.
                return;
            }

            // Step 3: Process the event.
            logger.LogInformation(
                "Processing MyEvent: EventId={EventId}, Message={Message}",
                myEvent.EventId, myEvent.Message);

            // Simulate async processing work (e.g., writing to a database,
            // calling a downstream service, triggering a workflow).
            await Task.Delay(TimeSpan.FromMilliseconds(200), cancellationToken);

            logger.LogInformation(
                "Successfully processed MyEvent for EventId={EventId}", myEvent.EventId);

            // Step 4: Delete the message ONLY after successful processing.
            // This is the at-least-once delivery guarantee — if we crash before
            // deleting, SQS will redeliver the message.
            await DeleteMessageAsync(sqsMessage, cancellationToken);
        }
        catch (JsonException ex)
        {
            logger.LogError(ex,
                "JSON deserialization failed for message {MessageId}. Deleting to avoid poison-pill loop.",
                sqsMessage.MessageId);
            await DeleteMessageAsync(sqsMessage, cancellationToken);
        }
        catch (Exception ex)
        {
            logger.LogError(ex,
                "Failed to process message {MessageId}. It will reappear after the visibility timeout.",
                sqsMessage.MessageId);
            // Do NOT delete — let SQS retry (and eventually the DLQ) handle it.
        }
    }

    private async Task DeleteMessageAsync(Message sqsMessage, CancellationToken cancellationToken)
    {
        try
        {
            await sqs.DeleteMessageAsync(QueueUrl, sqsMessage.ReceiptHandle, cancellationToken);
            logger.LogDebug("Deleted message {MessageId} from queue.", sqsMessage.MessageId);
        }
        catch (Exception ex)
        {
            // Deletion failure is non-fatal — the message will reappear after the
            // visibility timeout and may be processed again (idempotency matters here).
            logger.LogWarning(ex,
                "Failed to delete message {MessageId}. It may be processed again.",
                sqsMessage.MessageId);
        }
    }
}

// Represents the SNS notification envelope that wraps every message
// delivered to SQS via an SNS subscription. The actual event payload
// lives inside the Message field as a JSON-encoded string.
record SnsEnvelope(
    [property: JsonPropertyName("Type")]      string Type,
    [property: JsonPropertyName("MessageId")] string MessageId,
    [property: JsonPropertyName("TopicArn")]  string TopicArn,
    [property: JsonPropertyName("Message")]   string Message,
    [property: JsonPropertyName("Timestamp")] string Timestamp,
    [property: JsonPropertyName("MessageAttributes")]
        Dictionary<string, SnsMessageAttribute>? MessageAttributes
);

record SnsMessageAttribute(
    [property: JsonPropertyName("Type")]  string Type,
    [property: JsonPropertyName("Value")] string Value
);

// Must match the shape serialized by the producer.
record MyEvent(
    Guid EventId,
    string Message,
    DateTimeOffset CreatedAt
);

Full End-to-End Flow

Go to the SnsProducer folder and run the command dotnet run, then go to the SqsConsumer folder and run the command dotnet run and trigger and event by sending a request to http://localhost:5050/api/events (POST).

You can find all the code here. Thanks, and happy coding

This article demonstrates how to build a production-ready REST API using Hono with the @hono/zod-openapi library, which bridges the gap between Zod validation schemas and OpenAPI specifications, enabling a single source of truth for types, validation, and documentation.

The Problem

In traditional API development, you typically maintain three separate artifacts:

1. TypeScript types for compile-time safety

2. Runtime validators (like Joi, Yup, Zod, or manual validation)

3. OpenAPI/Swagger specification for documentation

This creates several problems:

• Duplication: Same structure defined three times

• Drift: Changes in one place don't automatically update others

• Maintenance burden: Keeping all three in sync is error-prone

• Source of bugs: Mismatches between types and validation

@hono/zod-openapi solves this by:

• Using Zod schemas as the single source of truth

• Automatically generating TypeScript types from schemas

• Automatically generating OpenAPI specifications from schemas

• Providing type-safe route handlers based on schema definitions

Understanding Core Concepts

Before diving into implementation, let's understand the key components of @hono/zod-openapi.

OpenAPIHono - The Enhanced Hono Instance

OpenAPIHono is an extended version of Hono's base class that adds OpenAPI-specific functionality.

import { OpenAPIHono } from '@hono/zod-openapi';

const app = new OpenAPIHono();

What OpenAPIHono Adds:

• .openapi() method: Registers routes with OpenAPI configuration

• .doc() method: Generates OpenAPI JSON specification endpoint

• Built-in validation: Automatically validates requests using Zod schemas

• Type inference: Derives TypeScript types from route configurations

Constructor Options:

const app = new OpenAPIHono({
  strict: boolean,        // URL path matching strictness
  defaultHook: Hook,      // Global validation error handler
});

• strict: When false, allows flexible path matching (e.g., trailing slashes)

• defaultHook: Function called when validation fails, customizing error responses

Comparison with Standard Hono:

// Standard Hono - no validation or OpenAPI
import { Hono } from 'hono';
const app = new Hono();
app.post('/todos', async (c) => {
  const body = await c.req.json(); // ❌ No validation, any type
  // Manual validation required
});

// OpenAPIHono - validation and OpenAPI included
import { OpenAPIHono } from '@hono/zod-openapi';
const app = new OpenAPIHono();
app.openapi(config, async (c) => {
  const body = c.req.valid('json'); // ✅ Validated and typed
  // Type: { title: string }
});

createRoute - Route Configuration Factory

The createRoute function in @hono/zod-openapi takes a route configuration object and returns an enhanced route object with a path conversion method.

import { createRoute } from '@hono/zod-openapi';

const route = createRoute({
  method: 'post',
  path: '/todos',
  request: { /* ... */ },
  responses: { /* ... */ },
});

createRoute accepts one parameter, which includes:

• method: HTTP method (e.g., 'get', 'post')

• path: OpenAPI path pattern (e.g., '/users/{id}'). Path parameters use curly braces: {paramName}. These must match parameter names in the request schema.

• request: Optional request validation schemas containing:

  • params: Zod schema for path parameters

  • query: Zod schema for query parameters

  • headers: Zod schema or array of schemas for request headers

  • cookies: Zod schema for cookies

  • body: Request body definition with:

    • content: Media type to schema mapping

    • description: Body description

    • required: Boolean indicating if body is required

• responses: Response definitions mapping status codes to response objects with content and descriptions

• hide: Optional boolean to hide from documentation

• middleware: Optional middleware handlers. Allows us to apply Hono middleware handlers specifically to individual routes, enabling per-route functionality like authentication, logging, caching, or custom request processing

• summary: A short summary of what the operation does

• description: A verbose explanation of the operation behavior

• operationId: Unique string used to identify the operation

• tags: A list of tags for API documentation control

• security: Declaration of which security schemes can be used

RouteHandler - Type-Safe Request Handler

RouteHandler is a generic type that infers request/response types from route configuration. RouteHandler takes four generic parameters:

• R extends RouteConfig: The route configuration type

• E extends Env = RouteConfigToEnv<R>: Environment type, inferred from route middleware

• I extends Input = ...: Combined input types from params, query, headers, cookies, form, and JSON

• P extends string = ConvertPathType<R['path']>: Path type converted from OpenAPI to Hono syntax

How Type Inference Works:

const config = createRoute({
  method: 'post',
  path: '/todos',
  request: {
    body: {
      content: {
        'application/json': {
          schema: z.object({
            title: z.string(),
          }),
        },
      },
    },
  },
  responses: {
    201: {
      content: {
        'application/json': {
          schema: z.object({
            id: z.string(),
            title: z.string(),
          }),
        },
      },
      description: 'Created',
    },
  },
});

// Extract config type
type Config = typeof config;

// Handler infers types from Config
const handler: RouteHandler<Config> = async (c) => {
  // c.req.valid('json') returns { title: string }
  const { title } = c.req.valid('json');

  // Return type must match response schema
  return c.json(
    {
      id: '123',
      title: title,
    },
    201
  );
};

The Magic: c.req.valid()

The valid() method is the key to type-safe validation:

c.req.valid('json')   // Returns validated body (from request.body.schema)
c.req.valid('query')  // Returns validated query params (from request.query)
c.req.valid('param')  // Returns validated path params (from request.params)
c.req.valid('header') // Returns validated headers (from request.header)

What valid() Does:

1. Validates the incoming data using the Zod schema

2. Transforms the data (e.g., z.coerce.number() converts strings)

3. Returns typed data (TypeScript knows the exact type)

4. Calls defaultHook if validation fails (never reaches your handler)

Type Safety Example:

const config = createRoute({
  request: {
    body: {
      content: {
        'application/json': {
          schema: z.object({
            title: z.string(),
            priority: z.number(),
          }),
        },
      },
    },
  },
  // ...
});

type Config = typeof config;
const handler: RouteHandler<Config> = async (c) => {
  const data = c.req.valid('json');

  // ✅ TypeScript knows these properties exist
  console.log(data.title);     // string
  console.log(data.priority);  // number

  // ❌ TypeScript error: Property doesn't exist
  console.log(data.description);
};

The Hook System - Validation Error Handling

Hooks intercept validation failures before they reach your handler. The Hook type takes four generic parameters:

• T: The validated data type

• E extends Env: Environment type

• P extends string: Path type

• R: Return type

And two parameters:

• result: An object containing:

  • target: The validation target (keyof ValidationTargets)

  • Either success data ({ success: true, data: T }) or error information ({ success: false, error: ZodError })

1. c: The Hono context object (same as in handlers)

Example Hook Implementation:

import type { Hook } from '@hono/zod-openapi';
import { BAD_REQUEST } from './http-status-codes.js';

export const defaultHook: Hook<any, any, any, any> = (result, c) => {
  // Only runs when validation fails
  if (!result.success) {
    return c.json(
      {
        success: false,
        error: {
          issues: result.error.issues.map(issue => ({
            path: issue.path.join('.'),
            message: issue.message,
            code: issue.code,
          })),
        },
      },
      BAD_REQUEST
    );
  }
  // If validation succeeds, return nothing (continue to handler)
};

How Hooks Are Applied:

// Option 1: Per-route hook
new OpenAPIHono().openapi(config, handler, hook);

// Option 2: Global default hook
new OpenAPIHono({ defaultHook }).openapi(config, handler);

When the Hook Runs:

1. Request arrives
2. @hono/zod-openapi validates request against schema
3. ❌ Validation fails
   → Hook is called
   → Returns error response
   → Handler never executes
4. ✅ Validation succeeds
   → Hook is not called
   → Handler executes with validated data

Zod OpenAPI Extensions

@hono/zod-openapi extends Zod with .openapi() method for OpenAPI-specific metadata.

import { z } from '@hono/zod-openapi';

const schema = z.string().openapi({
  example: 'example value',
  description: 'Field description',
  // ... other OpenAPI properties
});

Why Import from @hono/zod-openapi?

// ❌ Wrong - missing .openapi() extension
import { z } from 'zod';

// ✅ Correct - includes .openapi() extension
import { z } from '@hono/zod-openapi';

The @hono/zod-openapi package re-exports Zod with extensions. Always import from this package when defining schemas for OpenAPI routes. The .openapi() method added to Zod schemas accepts different parameter forms depending on how you want to enhance the schema for OpenAPI documentation.

Metadata Object Form: Takes an object with OpenAPI-specific properties:

• example: Example value for the schema

• description: Schema description

• deprecated: Boolean to mark as deprecated

• readOnly: Boolean for read-only properties

• writeOnly: Boolean for write-only properties

• param: Parameter metadata for path/query parameters

  • name: Parameter name

  • in: Parameter location ('path', 'query', 'header', 'cookie')

  • required

Schema Registration Form: Takes a string to register the schema as a referenced component in the OpenAPI document.

// Without name - inlined in OpenAPI spec
const todoSchema = z.object({
  title: z.string(),
});

// With name - creates reusable component
const todoSchema = z.object({
  title: z.string(),
}).openapi('Todo');

Generated OpenAPI (without name):

{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "title": { "type": "string" }
          }
        }
      }
    }
  }
}

Generated OpenAPI (with name):

{
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Todo"
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Todo": {
        "type": "object",
        "properties": {
          "title": { "type": "string" }
        }
      }
    }
  }
}

Benefits of Named Schemas:

• Smaller OpenAPI spec (no duplication)

• Better generated client SDKs

• Easier to reference in documentation

Building the Todo API - Step by Step

Now that we understand the @hono/zod-openapi fundamentals, let's build a complete TODO API. The project initial setup was explaned in the Hono: Setting up the development environment article.

Install dependencies:

npm install @hono/zod-openapi uuid @scalar/hono-api-reference http-problem-details

Dependency Breakdown:

• @hono/zod-openapi: The star of the show - provides OpenAPI integration

• @scalar/hono-api-reference: Interactive API documentation UI

• http-problem-details: RFC 7807 error response formatting

• uuid: For generating UUIDv7 identifiers

Step 1: Domain Model

// src/features/todos/todo.ts
import { z } from '@hono/zod-openapi';

export const todoSchema = z
  .object({
    todoId: z.uuidv7().openapi({
      example: '019af0ad-4ac8-7052-a609-24a539d353cd',
    }),
    title: z.string().min(1).openapi({
      example: 'Buy groceries',
    }),
    completed: z.boolean().default(false).openapi({
      example: false,
    }),
  })
  .openapi('Todo');

export type Todo = z.infer<typeof todoSchema>;

export const todos: Todo[] = [];

export const tags = ['Tasks'];

Schema Composition:

todoSchema serves as the base. We'll derive other schemas from it:

// Create schema - omit server-managed fields
const createSchema = todoSchema.omit({
  todoId: true,
  completed: true
});

// Update schema - all fields optional except ID
const updateSchema = todoSchema.partial().omit({
  todoId: true
});

// Query schema - for filtering
const querySchema = todoSchema.pick({
  completed: true
});

Step 2: Error Handling Schema

// src/schemas/problemDocument.ts
import { z } from '@hono/zod-openapi';

const errorSchema = z.object({
  path: z.string().openapi({
    example: 'title',
    description: 'The path to the field that failed validation',
  }),
  message: z.string().openapi({
    example: 'Too small: expected string to have >=1 characters',
    description: 'The validation error message',
  }),
  code: z.string().openapi({
    example: 'too_small',
    description: 'The validation error code',
  }),
});

export const problemDocumentSchema = z
  .object({
    type: z.string().optional().openapi({
      example: '/problems/resource-not-found',
      description: 'A URI reference that identifies the problem type',
    }),
    title: z.string().openapi({
      example: 'Resource not found',
      description: 'A short, human-readable summary of the problem type',
    }),
    status: z.number().openapi({
      example: 404,
      description: 'The HTTP status code',
    }),
    detail: z.string().optional().openapi({
      example: 'The requested todo was not found',
      description: 'A human-readable explanation specific to this occurrence',
    }),
    instance: z.string().optional().openapi({
      example: '/todos/019af0ad-4ac8-7052-a609-24a539d353cd',
      description: 'A URI reference that identifies the specific occurrence',
    }),
    errors: z.array(errorSchema).optional().openapi({
      description: 'Array of validation errors',
    }),
  })
  .openapi('ProblemDocument');

RFC 7807 Problem Details:

This standardized error format provides:

• Machine-readable error types

• Human-readable messages

• Traceable request instances

• Extensible with custom fields

Step 3: Validation Hook

// src/hooks.ts
import type { Hook } from '@hono/zod-openapi';
import { BAD_REQUEST } from '@/http-status-codes.js';
import { ProblemDocument } from 'http-problem-details';

export const defaultHook: Hook<any, any, any, any> = (result, c) => {
  if (!result.success) {
    return c.json(
      new ProblemDocument(
        {
          type: '/problems/validation-error',
          title: 'Validation Error',
          status: BAD_REQUEST,
          detail: 'The request contains invalid data',
          instance: c.req.path,
        },
        {
          errors: result.error.issues.map(err => ({
            path: err.path.join('.'),
            message: err.message,
            code: err.code,
          })),
        }
      ),
      BAD_REQUEST
    );
  }
};

Hook Execution Flow:

Client Request
    ↓
@hono/zod-openapi validates against schema
    ↓
  ❌ Validation Fails
    ↓
defaultHook is called with ZodError
    ↓
Hook transforms error to Problem Document
    ↓
Returns 400 response
    ↓
Handler NEVER executes

Zod Error Structure:

result.error.issues = [
  {
    code: 'too_small',
    minimum: 1,
    type: 'string',
    inclusive: true,
    exact: false,
    message: 'Too small: expected string to have >=1 characters',
    path: ['title'],
  }
]

Step 4: CREATE Operation

// src/features/todos/addTodo.ts
import { createRoute, OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';
import { v7 as uuidv7 } from 'uuid';
import { todoSchema, todos, tags } from './todo.js';
import { CREATED, BAD_REQUEST } from '@/http-status-codes.js';
import { defaultHook } from '@/hooks.js';
import { problemDocumentSchema } from '@/schemas/problemDocument.js';

// Derive create schema from base schema
const addTodoSchema = todoSchema
  .omit({ todoId: true, completed: true })
  .openapi('CreateTodo');

// Define route configuration
const config = createRoute({
  method: 'post',
  path: '/todos',
  tags: tags,
  request: {
    body: {
      content: {
        'application/json': {
          schema: addTodoSchema,
        },
      },
      description: 'Todo to create',
      required: true,
    },
  },
  responses: {
    [CREATED]: {
      content: {
        'application/json': {
          schema: todoSchema,
        },
      },
      description: 'Create a new todo',
    },
    [BAD_REQUEST]: {
      content: {
        'application/json': {
          schema: problemDocumentSchema,
        },
      },
      description: 'Invalid request data',
    },
  },
});

// Extract route type
type Config = typeof config;

// Type-safe handler
const handler: RouteHandler<Config> = async c => {
  // c.req.valid('json') returns { title: string }
  const { title } = c.req.valid('json');

  const todo = {
    todoId: uuidv7(),
    title,
    completed: false,
  };

  todos.push(todo);

  return c.json(todo, CREATED);
};

// Export as OpenAPIHono instance
export const addRoute = new OpenAPIHono({
  strict: false,
  defaultHook,
}).openapi(config, handler);

Breaking Down the Implementation:

1. Schema Derivation:

    const addTodoSchema = todoSchema.omit({
      todoId: true,    // Server generates
      completed: true   // Server sets default
    });
   

   Clients provide only title. Server manages todoId and completed.

2. Route Configuration:

    const config = createRoute({
      method: 'post',
      path: '/todos',
      // ...
    });
   

   This generates the OpenAPI specification for POST /todos.

3. Type Extraction:

    type Config = typeof config;
   

   Captures the full type of the configuration, used by RouteHandler.

4. Type-Safe Handler:

    const handler: RouteHandler<Config> = async c => {
      const { title } = c.req.valid('json');
      // TypeScript knows: { title: string }
    };
   

   RouteHandler<Config> infers parameter types from config.

5. Validation Flow:

    Request: POST /todos
    Body: { "title": "" }
        ↓
    @hono/zod-openapi validates against addTodoSchema
        ↓
    z.string().min(1) fails (empty string)
        ↓
    defaultHook called
        ↓
    Returns: 400 Bad Request with Problem Document
   

6. Route Export:

    export const addRoute = new OpenAPIHono({
      strict: false,
      defaultHook,
    }).openapi(config, handler);
   

   Creates a standalone Hono instance for this route, enabling modular composition.

Step 5: READ Operation - List with Pagination

// src/schemas/pagination.ts
import { z } from '@hono/zod-openapi';

const DEFAULT_PAGE_NUMBER = 1;
const DEFAULT_PAGE_SIZE = 10;
const MAX_PAGE_SIZE = 100;

export const paginationParametersSchema = z.object({
  pageNumber: z.coerce.number().min(1).optional().default(DEFAULT_PAGE_NUMBER),
  pageSize: z.coerce
    .number()
    .min(1)
    .max(MAX_PAGE_SIZE)
    .optional()
    .default(DEFAULT_PAGE_SIZE),
});

export const createPageSchema = <T>(itemSchema: z.ZodSchema<T>) =>
  z.object({
    items: z.array(itemSchema),
    pageNumber: z.number().min(1),
    pageSize: z.number().min(1).max(MAX_PAGE_SIZE),
    totalPages: z.number().min(0),
    totalCount: z.number().min(0),
  });

Generic Schema Factory:

createPageSchema<T>(itemSchema: z.ZodSchema<T>)

Creates a paginated response schema for any item type:

• createPageSchema(todoSchema) → Page<Todo>

• createPageSchema(userSchema) → Page<User>

Query Parameter Coercion:

pageNumber: z.coerce.number()

Query parameters arrive as strings:

GET /todos?pageNumber=2&pageSize=20
          ↓
{ pageNumber: "2", pageSize: "20" }  // Strings
          ↓
z.coerce.number() converts
          ↓
{ pageNumber: 2, pageSize: 20 }      // Numbers

// src/features/todos/listTodos.ts
import { createRoute, OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';
import { todoSchema, todos, tags } from './todo.js';
import {
  paginationParametersSchema,
  createPageSchema,
} from '@/schemas/pagination.js';
import { OK } from '@/http-status-codes.js';
import { defaultHook } from '@/hooks.js';

const config = createRoute({
  path: '/todos',
  method: 'get',
  tags: tags,
  request: {
    query: paginationParametersSchema,
  },
  responses: {
    [OK]: {
      content: {
        'application/json': {
          schema: createPageSchema(todoSchema),
        },
      },
      description: 'List all todos',
    },
  },
});

type Config = typeof config;

const handler: RouteHandler<Config> = async c => {
  // c.req.valid('query') returns { pageNumber: number, pageSize: number }
  const { pageNumber, pageSize } = c.req.valid('query');

  const startIndex = (pageNumber - 1) * pageSize;
  const endIndex = startIndex + pageSize;
  const paginatedTodos = todos.slice(startIndex, endIndex);

  return c.json(
    {
      items: paginatedTodos,
      pageNumber,
      pageSize,
      totalPages: Math.ceil(todos.length / pageSize),
      totalCount: todos.length,
    },
    OK
  );
};

export const listRoute = new OpenAPIHono({
  strict: false,
  defaultHook,
}).openapi(config, handler);

Query Parameter Validation:

request: {
  query: paginationParametersSchema,
}

This validates query parameters:

• pageNumber: Must be a number ≥ 1 (defaults to 1)

• pageSize: Must be between 1 and 100 (defaults to 10)

Type-Safe Query Access:

const { pageNumber, pageSize } = c.req.valid('query');
// TypeScript knows both are numbers, not string | undefined

Step6: READ Operation - Find by ID

// src/features/todos/findTodo.ts
import {
  createRoute,
  OpenAPIHono,
  z,
  type RouteHandler,
} from '@hono/zod-openapi';
import { todoSchema, todos, tags } from './todo.js';
import { ProblemDocument } from 'http-problem-details';
import { problemDocumentSchema } from '@/schemas/problemDocument.js';
import { OK, NOT_FOUND } from '@/http-status-codes.js';
import { defaultHook } from '@/hooks.js';

const config = createRoute({
  path: '/todos/{todoId}',
  method: 'get',
  tags: tags,
  request: {
    params: z.object({
      todoId: z.uuidv7().openapi({
        param: {
          name: 'todoId',
          in: 'path',
          required: true,
        },
        example: '019af0ad-4ac8-7052-a609-24a539d353cd',
      }),
    }),
  },
  responses: {
    [OK]: {
      content: {
        'application/json': {
          schema: todoSchema,
        },
      },
      description: 'Get a todo by ID',
    },
    [NOT_FOUND]: {
      content: {
        'application/json': {
          schema: problemDocumentSchema,
        },
      },
      description: 'Todo not found',
    },
  },
});

type Config = typeof config;

const handler: RouteHandler<Config> = async c => {
  // c.req.valid('param') returns { todoId: string }
  const { todoId } = c.req.valid('param');
  const todo = todos.find(t => t.todoId === todoId);

  if (!todo) {
    return c.json(
      new ProblemDocument({
        type: '/problems/resource-not-found',
        title: 'Resource not found',
        status: NOT_FOUND,
        detail: `Todo with id ${todoId} not found`,
        instance: c.req.path,
      }),
      NOT_FOUND
    );
  }

  return c.json(todo, OK);
};

export const findRoute = new OpenAPIHono({
  strict: false,
  defaultHook,
}).openapi(config, handler);

Path Parameter Configuration:

params: z.object({
  todoId: z.uuidv7().openapi({
    param: {
      name: 'todoId',     // Must match {todoId} in path
      in: 'path',         // Parameter location
      required: true,     // Path params always required
    },
  }),
})

Critical: Name Must Match Path Placeholder:

path: '/todos/{todoId}',
params: z.object({
  todoId: z.uuidv7(),  // ✅ Matches {todoId}
}),

path: '/todos/{id}',
params: z.object({
  todoId: z.uuidv7(),  // ❌ Doesn't match {id}
}),

Validation Flow:

Request: GET /todos/invalid-uuid
     ↓
@hono/zod-openapi validates 'invalid-uuid'
     ↓
z.uuidv7() fails
     ↓
defaultHook called
     ↓
Returns: 400 Bad Request

Request: GET /todos/019af0ad-4ac8-7052-a609-24a539d353cd
     ↓
Validation succeeds
     ↓
Handler executes
     ↓
Todo not in array
     ↓
Returns: 404 Not Found with Problem Document

Step 7: UPDATE Operation - Mark Complete

// src/features/todos/checkTodo.ts
import { createRoute, OpenAPIHono, type RouteHandler } from '@hono/zod-openapi';
import { todoSchema, todos, tags } from './todo.js';
import { z } from '@hono/zod-openapi';
import { ProblemDocument } from 'http-problem-details';
import { problemDocumentSchema } from '@/schemas/problemDocument.js';
import { OK, NOT_FOUND } from '@/http-status-codes.js';
import { defaultHook } from '@/hooks.js';

const config = createRoute({
  path: '/todos/{todoId}/check',
  method: 'put',
  tags: tags,
  request: {
    params: z.object({
      todoId: z.uuidv7().openapi({
        param: {
          name: 'todoId',
          in: 'path',
          required: true,
        },
        example: '019af0ad-4ac8-7052-a609-24a539d353cd',
      }),
    }),
  },
  responses: {
    [OK]: {
      content: {
        'application/json': {
          schema: todoSchema,
        },
      },
      description: 'Check a todo as completed',
    },
    [NOT_FOUND]: {
      content: {
        'application/json': {
          schema: problemDocumentSchema,
        },
      },
      description: 'Todo not found',
    },
  },
});

type Config = typeof config;

const handler: RouteHandler<Config> = async c => {
  const { todoId } = c.req.valid('param');
  const todo = todos.find(t => t.todoId === todoId);

  if (!todo) {
    return c.json(
      new ProblemDocument({
        type: '/problems/resource-not-found',
        title: 'Resource not found',
        status: NOT_FOUND,
        detail: `Todo with id ${todoId} not found`,
        instance: c.req.path,
      }),
      NOT_FOUND
    );
  }

  todo.completed = true;
  return c.json(todo, OK);
};

export const checkRoute = new OpenAPIHono({
  strict: false,
  defaultHook,
}).openapi(config, handler);

Action Endpoint Pattern:

path: '/todos/{todoId}/check',
method: 'put',

This is an "action" endpoint:

• No request body needed

• Performs a specific action (checking todo)

• Idempotent (calling multiple times same effect)

Step 8: Assembling the Application

// src/index.ts
import { serve } from '@hono/node-server';
import { ENV } from '@/env.js';
import { OpenAPIHono } from '@hono/zod-openapi';
import { addRoute } from '@/features/todos/addTodo.js';
import { Scalar } from '@scalar/hono-api-reference';
import { listRoute } from './features/todos/listTodos.js';
import { findRoute } from './features/todos/findTodo.js';
import { checkRoute } from './features/todos/checkTodo.js';

const app = new OpenAPIHono()
  .doc('/doc', {
    openapi: '3.0.0',
    info: {
      version: '1.0.0',
      title: 'Todo API',
    },
  })
  .get(
    '/reference',
    Scalar({
      url: '/doc',
      theme: 'kepler',
      layout: 'classic',
      darkMode: true,
    })
  )
  .route('/', addRoute)
  .route('/', listRoute)
  .route('/', findRoute)
  .route('/', checkRoute);

serve(
  {
    fetch: app.fetch,
    port: ENV.PORT,
  },
  info => {
    console.log(
      `Server(${ENV.NODE_ENV}) is running on http://localhost:${info.port}`
    );
  }
);

The .doc() Method:

.doc('/doc', {
  openapi: '3.0.0',
  info: {
    version: '1.0.0',
    title: 'Todo API',
  },
})

This registers GET /doc endpoint that returns the OpenAPI JSON specification. The spec is automatically generated from all registered routes.

What Gets Generated:

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Todo API"
  },
  "paths": {
    "/todos": {
      "get": { /* listRoute config */ },
      "post": { /* addRoute config */ }
    },
    "/todos/{todoId}": {
      "get": { /* findRoute config */ }
    },
    "/todos/{todoId}/check": {
      "put": { /* checkRoute config */ }
    }
  },
  "components": {
    "schemas": {
      "Todo": { /* todoSchema */ },
      "CreateTodo": { /* addTodoSchema */ },
      "ProblemDocument": { /* problemDocumentSchema */ }
    }
  }
}

Scalar Documentation UI:

.get(
  '/reference',
  Scalar({
    url: '/doc',           // Points to OpenAPI spec endpoint
    theme: 'kepler',       // Visual theme
    layout: 'classic',     // Layout style
    darkMode: true,        // Enable dark mode
  })
)

Access at http://localhost:3000/reference for interactive API documentation.

Mounting Routes:

.route('/', addRoute)
.route('/', listRoute)
.route('/', findRoute)
.route('/', checkRoute)

Each route is a complete OpenAPIHono instance. .route() mounts them on the main app at the specified base path.

Why This Pattern?

• Modularity: Each route is self-contained

• Testing: Test routes independently

• Organization: Related code stays together

• Reusability: Routes can be mounted on different apps

Advanced Patterns

Middleware Integration

OpenAPIHono is fully compatible with Hono middleware:

import { logger } from 'hono/logger';
import { cors } from 'hono/cors';
import { bearerAuth } from 'hono/bearer-auth';

const app = new OpenAPIHono()
  .use('*', logger())
  .use('/api/*', cors())
  .use('/api/admin/*', bearerAuth({ token: 'secret' }));

Documenting Authentication:

.doc('/doc', {
  openapi: '3.0.0',
  info: { /* ... */ },
  components: {
    securitySchemes: {
      bearerAuth: {
        type: 'http',
        scheme: 'bearer',
        bearerFormat: 'JWT',
      },
    },
  },
  security: [{ bearerAuth: [] }],
})

Custom Validation Hooks Per Route

Override the default hook for specific routes:

const customHook: Hook<any, any, any, any> = (result, c) => {
  if (!result.success) {
    // Custom error handling for this specific route
    return c.json(
      {
        error: 'Custom error format',
        details: result.error.issues,
      },
      400
    );
  }
};

export const specialRoute = new OpenAPIHono()
  .openapi(config, handler, customHook);  // Route-specific hook

Type-Safe Response Helpers

Create helpers for common responses:

const createSuccessResponse = <T extends z.ZodSchema>(schema: T) => ({
  [OK]: {
    content: {
      'application/json': {
        schema,
      },
    },
    description: 'Success',
  },
});

const createErrorResponses = () => ({
  [BAD_REQUEST]: {
    content: {
      'application/json': {
        schema: problemDocumentSchema,
      },
    },
    description: 'Validation error',
  },
  [NOT_FOUND]: {
    content: {
      'application/json': {
        schema: problemDocumentSchema,
      },
    },
    description: 'Resource not found',
  },
});

// Usage
const config = createRoute({
  method: 'get',
  path: '/todos',
  responses: {
    ...createSuccessResponse(createPageSchema(todoSchema)),
    ...createErrorResponses(),
  },
});

Testing

Running the Application

npm run dev

Access:

• API: http://localhost:3000

• Documentation: http://localhost:3000/reference

• OpenAPI Spec: http://localhost:3000/doc

The @hono/zod-openapi library eliminates the traditional pain points of API development by deriving types, validation, and documentation from a single schema definition. This approach scales from simple APIs to complex enterprise systems while maintaining type safety and developer experience. You can find all the code here. Thanks, and happy coding

Prerequisites

Before starting, ensure you have installed:

• Node.js 20 or higher

• npm 10 or higher

• Git

What is a Monorepo?

A monorepo (monolithic repository) is a software development strategy where multiple projects are stored in a single repository. Instead of having separate repositories for your frontend, backend, and shared libraries, everything lives together under one roof.

Monorepo vs. Polyrepo

To understand monorepos, let's compare them with the traditional polyrepo approach:

Polyrepo (Multiple Repositories):

github.com/your-org/frontend    → React application
github.com/your-org/backend     → Hono API
github.com/your-org/shared-ui   → Component library
github.com/your-org/utils       → Shared utilities

Monorepo (Single Repository):

github.com/your-org/platform
├── apps/
│   ├── frontend/    → React application
│   └── backend/     → Hono API
└── packages/
    ├── shared-ui/   → Component library
    └── utils/       → Shared utilities

How Monorepos Work

In a JavaScript/TypeScript monorepo, package managers like npm, Yarn, or pnpm provide workspaces functionality. Workspaces allow you to:

1. Link packages locally: Instead of publishing @your-org/utils to npm and installing it in your frontend, the package manager creates symlinks between workspace packages. Changes are immediately available without publishing.

2. Hoist shared dependencies: Common dependencies (like TypeScript or React) are installed once at the root level and shared across all packages, reducing disk space and ensuring version consistency.

3. Run scripts across packages: Execute commands like npm run build across all packages or target specific workspaces with flags like -w @your-org/frontend.

Monorepo Tools

While npm workspaces (which we'll use in this guide) provide basic monorepo functionality, specialized tools offer additional features:

For this guide, we'll use npm workspaces as it requires no additional dependencies and covers the essential functionality needed for most projects.

Why a Monorepo?

Before we begin, let's understand the benefits of a monorepo architecture:

• Shared tooling: Configure ESLint, Prettier, and TypeScript once for all packages

• Atomic commits: Changes spanning the frontend and backend can be committed together

• Simplified dependency management: Shared dependencies are hoisted to the root

• Cross-package imports: Frontend can import types directly from backend

• Unified CI/CD: A single pipeline handles all packages

Step 1: Initialize the Project

Start by creating your project directory and initializing git:

mkdir node-monorepo
cd node-monorepo
git init

Create the folder structure for our monorepo:

mkdir -p apps/backend/src
mkdir -p apps/frontend/src
mkdir packages

We use the apps/packages convention, which is widely adopted in the JavaScript ecosystem:

• apps/ contains deployable applications (our backend and frontend)

• packages/ is reserved for shared libraries (we'll leave it empty for now)

Step 2: Create the Root Package Configuration

2.1 Initialize package.json

Initialize the root package using npm:

npm init -y

Now open package.json and replace its contents with:

{
  "name": "node-monorepo",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "workspaces": [
    "apps/*",
    "packages/*"
  ],
  "scripts": {
    "dev": "concurrently \"npm:dev:backend\" \"npm:dev:frontend\"",
    "dev:backend": "npm run dev -w @node-monorepo/backend",
    "dev:frontend": "npm run dev -w @node-monorepo/frontend",
    "build:backend": "npm run build -w @node-monorepo/backend",
    "build:frontend": "npm run build -w @node-monorepo/frontend",
    "build": "npm run build:backend && npm run build:frontend",
    "start:backend": "npm run start -w @node-monorepo/backend",
    "preview:frontend": "npm run preview -w @node-monorepo/frontend",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "lint:format": "npm run lint:fix && npm run format",
    "prepare": "husky || true",
    "commit": "commit"
  },
  "devDependencies": {
    "@commitlint/cli": "^20.3.1",
    "@commitlint/config-conventional": "^20.3.1",
    "@commitlint/prompt-cli": "^20.3.1",
    "@eslint/js": "^9.18.0",
    "concurrently": "^9.1.2",
    "eslint": "^9.18.0",
    "eslint-config-prettier": "^10.0.1",
    "eslint-plugin-react-hooks": "^7.0.1",
    "eslint-plugin-react-refresh": "^0.4.18",
    "globals": "^17.0.0",
    "husky": "^9.1.7",
    "prettier": "^3.4.2",
    "typescript": "^5.7.3",
    "typescript-eslint": "^8.21.0"
  }
}

Let's understand the key properties:

About the scripts:

• dev: Runs both servers in parallel using concurrently. We can't use npm run dev --workspaces because that runs scripts sequentially, not in parallel.

• -w @node-monorepo/backend: The -w flag targets a specific workspace by name.

• prepare: Runs automatically after npm install to set up Husky. The || true prevents failures in CI environments where git might not be initialized.

About devDependencies:

All shared tooling (ESLint, Prettier, TypeScript, Husky, Commitlint) lives at the root. This ensures:

• Consistent versions across all packages

• Single source of truth for configuration

• Reduced duplication in node_modules

2.2 Create tsconfig.base.json

In a monorepo, TypeScript configurations often share many options. Instead of duplicating them in every workspace, we create a base configuration that all others extend from.

Create tsconfig.base.json in the project root:

{
  "compilerOptions": {
    "target": "ES2023",
    "module": "ESNext",
    "skipLibCheck": true,
    "verbatimModuleSyntax": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedSideEffectImports": true,
    "allowUnreachableCode": false,
    "noErrorTruncation": true,
    "noPropertyAccessFromIndexSignature": true,
    "resolveJsonModule": true,
    "esModuleInterop": true
  }
}

Key options explained:

2.3 Create Root tsconfig.json

Now, create tsconfig.json that extends the base configuration. This config is specifically for the root-level config files (ESLint, Prettier, Commitlint):

{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "lib": ["ES2023"],
    "types": ["node"],
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "moduleDetection": "force",
    "noEmit": true
  },
  "include": ["eslint.config.ts", "commitlint.config.ts", "prettier.config.ts"]
}

By using "extends": "./tsconfig.base.json", we inherit all the strict options from the base config and only specify what's unique to this context:

• lib: ["ES2023"]: Standard library types (no DOM since these run in Node.js)

• types: ["node"]: Node.js type definitions

• noEmit: true: We're only type-checking, not compiling

• strict: true: Enables all strict type-checking options

Step 3: Create the Backend (Hono API)

3.1 Initialize Backend package.json

Navigate to the backend directory and initialize the package:

cd apps/backend
npm init -y

Open apps/backend/package.json and replace its contents with:

{
  "name": "@node-monorepo/backend",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "tsx watch src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "@hono/node-server": "^1.13.8",
    "hono": "^4.6.18"
  },
  "devDependencies": {
    "@types/node": "^25.0.9",
    "tsx": "^4.19.4"
  }
}

Key decisions:

• Scoped name @node-monorepo/backend: Follows npm's scoped package convention. This prevents naming conflicts and makes workspace references clearer.

• tsx for development: A TypeScript execution engine that provides fast compilation via esbuild and includes watch mode for automatic reloading.

• Hono + @hono/node-server: Hono is a lightweight, fast web framework. The @hono/node-server adapter allows it to run on Node.js.

3.2 Create Backend tsconfig.json

Create apps/backend/tsconfig.json that extends the base configuration:

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "target": "ESNext",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "sourceMap": true,
    "types": ["node"],
    "jsx": "react-jsx",
    "jsxImportSource": "hono/jsx",
    "removeComments": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "baseUrl": ".",
    "paths": {
      "#/*": ["./src/*"]
    }
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Notice how much shorter this is compared to a standalone config. By extending ../../tsconfig.base.json, we inherit all the strict options and only specify what's unique to the backend.

Important options explained:

Why #/ for the path alias? We use #/ for backend and @/ for frontend to create a clear visual distinction. In the backend code, you can write:

import { someUtil } from '#/utils/helper';
// Instead of: import { someUtil } from '../../../utils/helper';

3.3 Create the Backend API

Create the main entry point at apps/backend/src/index.ts:

import { Hono } from 'hono';
import { cors } from 'hono/cors';
import { serve } from '@hono/node-server';

const app = new Hono();

app.use(
  '/api/*',
  cors({
    origin: 'http://localhost:5173',
  })
);

app.get('/api/hello', c => {
  return c.json({ message: 'Hello World from Hono!' });
});

const port = 3000;
console.log(`Server is running on http://localhost:${port}`);

serve({
  fetch: app.fetch,
  port,
});

Let's break down this code:

1. CORS middleware: The frontend runs on port 5173 (Vite's default), so we explicitly allow that origin. Without this, the browser would block requests from the frontend to the backend due to the same-origin policy.

2. /api/* prefix: Prefixing all API routes with /api is a common convention that:

   • Makes it easy to distinguish API calls from static assets

   • Simplifies reverse proxy configuration in production

   • Allows CORS to be applied only to API routes

3. /api/hello endpoint: A simple GET endpoint that returns a JSON message. The c parameter is Hono's context object, which provides request/response utilities.

4. serve() function: The @hono/node-server adapter that starts the HTTP server.

Step 4: Create the Frontend (React + Vite)

4.1 Initialize Frontend package.json

Navigate to the frontend directory and initialize the package:

cd apps/frontend
npm init -y

Open apps/frontend/package.json and replace its contents with:

{
  "name": "@node-monorepo/frontend",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "@types/react": "^19.0.7",
    "@types/react-dom": "^19.0.3",
    "@vitejs/plugin-react": "^5.1.2",
    "vite": "^7.3.1"
  }
}

Why separate dependencies from the root? Runtime dependencies (react, react-dom) are placed in each workspace because:

• They are specific to that application

• They will be bundled into the final build

• Different apps might need different versions

4.2 Create Frontend TypeScript Configuration

The frontend uses a multi-file TypeScript configuration pattern recommended by Vite. This allows separate settings for browser code and Node.js code (like vite.config.ts).

Create apps/frontend/tsconfig.json:

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ]
}

This file doesn't compile anything—it orchestrates the other configs using project references. This enables:

• Faster incremental builds

• Separate configurations for browser and Node.js code

• Better IDE support

Create apps/frontend/tsconfig.app.json for browser code:

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "target": "ES2022",
    "useDefineForClassFields": true,
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "moduleDetection": "force",
    "noEmit": true,
    "jsx": "react-jsx",
    "paths": {
      "@/*": ["./src/*"],
      "#/*": ["../backend/src/*"]
    }
  },
  "include": ["src"]
}

Key points:

• extends: Inherits strict options from the base config

• lib: ["ES2022", "DOM", "DOM.Iterable"]: Includes browser APIs (DOM)

• moduleResolution: "bundler": Optimized for bundlers like Vite

• paths: Defines two aliases:

  • @/* for internal frontend imports

  • #/* for importing backend types (cross-workspace)

Cross-workspace type imports: The #/* path pointing to ../backend/src/* allows the frontend to import types directly from the backend:

// In frontend, you could import backend types like this:
import type { SomeApiResponse } from '#/types';

Create apps/frontend/tsconfig.node.json for Vite config:

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "lib": ["ES2023"],
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "moduleDetection": "force",
    "noEmit": true
  },
  "include": ["vite.config.ts"]
}

This config is much smaller because it extends the base. It exists separately because vite.config.ts runs in Node.js, not the browser—notice there's no DOM in the lib array.

4.3 Create Vite Configuration

Create apps/frontend/vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '#': path.resolve(__dirname, '../backend/src'),
    },
  },
});

Important: Path aliases must be defined in both tsconfig.app.json (for TypeScript type checking) and vite.config.ts (for the bundler's module resolution). TypeScript handles type checking, while Vite handles the actual import resolution during development and build.

4.4 Create HTML Entry Point

Create apps/frontend/index.html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Node Monorepo</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Vite uses index.html as the entry point. The <script type="module"> tag points to our main TypeScript file.

4.5 Create React Application

Create the main entry file at apps/frontend/src/main.tsx:

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App.tsx';
import './index.css';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>
);

StrictMode helps identify potential problems by activating additional checks during development.

Create the App component at apps/frontend/src/App.tsx:

import { useEffect, useState } from 'react';

function App() {
  const [message, setMessage] = useState<string>('Loading...');
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    fetch('http://localhost:3000/api/hello')
      .then(response => {
        if (!response.ok) {
          throw new Error('Failed to fetch');
        }
        return response.json();
      })
      .then(data => {
        setMessage(data.message);
      })
      .catch(err => {
        setError(err.message);
      });
  }, []);

  return (
    <div className="container">
      <h1>Node Monorepo</h1>
      {error ? (
        <p className="error">Error: {error}</p>
      ) : (
        <p className="message">{message}</p>
      )}
    </div>
  );
}

export default App;

This component:

1. Uses useState to manage the message and error state

2. Uses useEffect to fetch data from the backend when the component mounts

3. Displays either the message or an error

Create the styles at apps/frontend/src/index.css:

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

body {
  font-family:
    -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu,
    sans-serif;
  min-height: 100vh;
  display: flex;
  align-items: center;
  justify-content: center;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

.container {
  text-align: center;
  padding: 2rem;
  background: white;
  border-radius: 1rem;
  box-shadow: 0 10px 40px rgba(0, 0, 0, 0.2);
}

h1 {
  color: #333;
  margin-bottom: 1rem;
}

.message {
  font-size: 1.25rem;
  color: #667eea;
}

.error {
  color: #e53e3e;
}

Step 5: Configure ESLint

ESLint 9 introduced the flat config format, replacing the legacy .eslintrc files. Create eslint.config.ts at the project root:

import jseslint from '@eslint/js';
import tseslint from 'typescript-eslint';
import { defineConfig, globalIgnores } from 'eslint/config';
import prettierConfig from 'eslint-config-prettier';
import reactHooks from 'eslint-plugin-react-hooks';
import reactRefresh from 'eslint-plugin-react-refresh';
import globals from 'globals';

export default defineConfig(
  globalIgnores(['**/dist/**/*', '**/node_modules/**/*', '**/*.tsbuildinfo']),
  jseslint.configs.recommended,
  tseslint.configs.recommended,
  prettierConfig,
  {
    files: ['eslint.config.ts', 'commitlint.config.ts', 'prettier.config.ts'],
    languageOptions: {
      globals: globals.node,
      parserOptions: {
        tsconfigRootDir: import.meta.dirname,
        project: './tsconfig.json',
      },
    },
  },
  {
    files: ['apps/backend/**/*.{ts,tsx}'],
    languageOptions: {
      globals: globals.node,
      parserOptions: {
        tsconfigRootDir: import.meta.dirname,
        project: './apps/backend/tsconfig.json',
      },
    },
  },
  {
    files: ['apps/frontend/src/**/*.{ts,tsx}'],
    extends: [reactHooks.configs.flat.recommended, reactRefresh.configs.vite],
    languageOptions: {
      globals: globals.browser,
      parserOptions: {
        tsconfigRootDir: import.meta.dirname,
        project: './apps/frontend/tsconfig.app.json',
      },
    },
  },
  {
    files: ['apps/frontend/vite.config.ts'],
    languageOptions: {
      globals: globals.node,
      parserOptions: {
        tsconfigRootDir: import.meta.dirname,
        project: './apps/frontend/tsconfig.node.json',
      },
    },
  }
);

Let's understand each part:

5.1 Global Ignores

globalIgnores(['**/dist/**/*', '**/node_modules/**/*', '**/*.tsbuildinfo']),

This replaces the old .eslintignore file. We ignore:

• dist/: Build output directories

• node_modules/: Dependencies

• *.tsbuildinfo: TypeScript incremental compilation cache

5.2 Base Configurations

jseslint.configs.recommended,
tseslint.configs.recommended,
prettierConfig,

These apply to all files:

• jseslint.configs.recommended: ESLint's recommended JavaScript rules

• tseslint.configs.recommended: TypeScript-specific rules

• prettierConfig: Must come after other configs to disable rules that conflict with Prettier

5.3 File-Specific Configurations

Each block targets specific files with appropriate settings:

Root config files:

{
  files: ['eslint.config.ts', 'commitlint.config.ts', 'prettier.config.ts'],
  languageOptions: {
    globals: globals.node,  // Node.js globals (process, __dirname, etc.)
    parserOptions: {
      tsconfigRootDir: import.meta.dirname,
      project: './tsconfig.json',  // Points to root tsconfig
    },
  },
},

Backend files:

{
  files: ['apps/backend/**/*.{ts,tsx}'],
  languageOptions: {
    globals: globals.node,
    parserOptions: {
      tsconfigRootDir: import.meta.dirname,
      project: './apps/backend/tsconfig.json',
    },
  },
},

Frontend source files:

{
  files: ['apps/frontend/src/**/*.{ts,tsx}'],
  extends: [reactHooks.configs.flat.recommended, reactRefresh.configs.vite],
  languageOptions: {
    globals: globals.browser,  // Browser globals (window, document, etc.)
    parserOptions: {
      tsconfigRootDir: import.meta.dirname,
      project: './apps/frontend/tsconfig.app.json',
    },
  },
},

Note the React-specific plugins:

• reactHooks.configs.flat.recommended: Enforces Rules of Hooks

• reactRefresh.configs.vite: Ensures components are compatible with hot module replacement

Vite config file:

{
  files: ['apps/frontend/vite.config.ts'],
  languageOptions: {
    globals: globals.node,  // Vite config runs in Node.js
    parserOptions: {
      tsconfigRootDir: import.meta.dirname,
      project: './apps/frontend/tsconfig.node.json',
    },
  },
},

Why specify a project for each file pattern? TypeScript-ESLint can provide type-aware linting when it knows which tsconfig.json applies to each file. This enables catching more errors like unused variables that TypeScript alone might not flag.

Important: You must use eslint-plugin-react-hooks version 7 or higher. Earlier versions don't export a flat config (configs.flat.recommended is only available in v7+).

Step 6: Configure Prettier

Create prettier.config.ts at the project root:

import type { Config } from 'prettier';

const config: Config = {
  trailingComma: 'es5',
  singleQuote: true,
  arrowParens: 'avoid',
  endOfLine: 'crlf',
};

export default config;

Options explained:

Create .prettierignore at the project root to exclude generated files:

**/dist/
**/*.tsbuildinfo
**/package-lock.json

Why ignore these?

• dist/: Generated build output—formatting would be overwritten on next build

• *.tsbuildinfo: Binary cache files

• package-lock.json: Auto-generated by npm, formatting changes create noise in git history

Step 7: Configure Commitlint and Husky

7.1 Create Commitlint Configuration

Commitlint ensures all commit messages follow a consistent format. Create commitlint.config.ts at the project root:

import type { UserConfig } from '@commitlint/types';

const config: UserConfig = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'scope-enum': [2, 'always', ['backend', 'frontend', 'repo']],
    'subject-case': [2, 'always', ['sentence-case', 'lower-case']],
  },
};

export default config;

Understanding rule format: [level, applicable, value]

• Level: 0 = disabled, 1 = warning, 2 = error

• Applicable: 'always' (must match) or 'never' (must not match)

• Value: The rule configuration

Our rules:

scope-enum: Restricts commit scopes to predefined values:

feat(backend): Add user authentication  ✓
fix(frontend): Resolve button styling   ✓
chore(repo): Update dependencies        ✓
feat(api): Add endpoint                 ✗ ('api' not in allowed scopes)

subject-case: Allows either sentence case or lowercase:

feat: Add new feature     ✓
feat: add new feature     ✓
feat: ADD NEW FEATURE     ✗

7.2 Conventional Commit Format

The conventional commit format is:

<type>(<scope>): <subject>

[optional body]

[optional footer]

Common types:

7.3 Set Up Husky

Create the .husky directory and hook files:

mkdir -p .husky

Create .husky/pre-commit with the following content:

npm run lint
npm run format:check

This runs ESLint and checks Prettier formatting before each commit. If either fails, the commit is aborted, ensuring only properly formatted and linted code enters the repository.

Create .husky/commit-msg with the following content:

npx commitlint --edit $1

This validates the commit message against your commitlint rules. The $1 argument is the path to the temporary file containing the commit message.

Make the hooks executable (Unix/macOS):

chmod +x .husky/pre-commit
chmod +x .husky/commit-msg

Step 8: Install Dependencies and Test

8.1 Install All Dependencies

From the project root, run:

npm install

npm workspaces will:

1. Install root devDependencies

2. Install each workspace's dependencies

3. Hoist shared dependencies to the root node_modules

4. Create symlinks for workspace packages

5. Run the prepare script, initializing Husky

8.2 Verify the Setup

Run ESLint to check for errors:

npm run lint

Check Prettier formatting:

npm run format:check

If there are formatting issues, fix them:

npm run format

8.3 Start the Development Servers

npm run dev

This runs both servers concurrently:

• Backend at http://localhost:3000

• Frontend at http://localhost:5173

Open your browser to http://localhost:5173. You should see the "Node Monorepo" heading with the message "Hello World from Hono!" fetched from the backend.

8.4 Test the Build

npm run build

This builds both the backend (TypeScript compilation) and frontend (Vite production build).

8.5 Test Commit Hooks

Try making a commit to verify the hooks work:

git add .
git commit -m "feat(repo): Initial monorepo setup"

The pre-commit hook will run lint and format checks. The commit-msg hook will validate your commit message format.

Final Project Structure

node-monorepo/
├── apps/
│   ├── backend/
│   │   ├── src/
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── tsconfig.json          # Extends tsconfig.base.json
│   └── frontend/
│       ├── src/
│       │   ├── App.tsx
│       │   ├── main.tsx
│       │   └── index.css
│       ├── index.html
│       ├── package.json
│       ├── tsconfig.json          # Project references
│       ├── tsconfig.app.json      # Extends tsconfig.base.json
│       ├── tsconfig.node.json     # Extends tsconfig.base.json
│       └── vite.config.ts
├── packages/
├── .husky/
│   ├── pre-commit
│   └── commit-msg
├── package.json
├── tsconfig.base.json             # Shared TypeScript options
├── tsconfig.json                  # Extends tsconfig.base.json
├── eslint.config.ts
├── prettier.config.ts
├── commitlint.config.ts
└── .prettierignore

This template provides a solid foundation for building full-stack TypeScript applications with modern tooling and best practices. You can find all the code here. Thanks, and happy coding

We'll use a price tracker application as our example, a system that manages stores, products, and price histories. The starting code is available at https://github.com/raulnq/price-tracker/tree/drizzle.

By the end of this guide, we'll have built:

• A complete test infrastructure with setup and teardown.

• Reusable DSL functions for all API operations.

• Custom assertion helpers for fluent testing.

• Comprehensive test suites for stores.

Prerequisites

Before starting, ensure we have:

• Node.js 24+ installed.

• The price-tracker project cloned from the repository.

• Docker Desktop installed.

• A PostgreSQL database running (use npm run database: up)

• Dependencies installed (npm install).

Step 1: Install Testing Dependencies

First, let's add the testing library we need. We'll use @faker-js/faker for generating unique test data:

npm install --save-dev @faker-js/faker

Faker is a JavaScript library that generates massive amounts of fake but realistic data. It's essential for testing because:

• Unique identifiers: Prevents test collisions when tests share a database.

• Realistic data: Makes tests more representative of real-world scenarios.

• Random variations: Helps uncover edge cases through varied input.

Common methods we'll use:

faker.string.uuid()     // '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'
faker.number.float({ min: 1, max: 1000, fractionDigits: 2 })  // 123.45

Step 2: Configure the Test Script

Update package.json to add the test script:

{
  "scripts": {
    "test": "cross-env NODE_ENV=test tsx --import ./tests/setup.ts --test ./tests/**/*.test.ts"
  }
}

This configuration:

• cross-env NODE_ENV=test: Sets the environment to test mode for different configurations (like a test database).

• tsx: Enables TypeScript execution directly without pre-compilation.

• --import ./tests/setup.ts: Imports the setup file before running tests.

• --test ./tests/**/*.test.ts: Uses Node.js's native test runner with glob patterns.

Step 3: Create the Test Directory Structure

Create the following folder structure:

tests/
├── setup.ts
├── utils.ts
├── errors.ts
├── assertions.ts
├── stores/
│   └── stores-dsl.ts
└── products/
    └── products-dsl.ts

Step 4: Create the Global Test Setup

The setup file handles global test lifecycle management. Create tests/setup.ts:

import { after } from 'node:test';
import { client } from '@/database/client.js';

after(async () => {
  await client.$client.end();
});

This ensures that after all tests complete, the database connection pool is properly closed. The after hook from Node's test runner executes once after all tests finish, preventing hanging connections.

Step 5: Create Utility Functions

Create tests/utils.ts with a helper for handling JSON date serialization:

export const parseDatesFromJSON = <T>(
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  json: any,
  dateFields: (keyof T)[]
): T => {
  const result = { ...json };
  for (const field of dateFields) {
    if (result[field]) {
      result[field] = new Date(result[field]);
    }
  }
  return result as T;
};

When JSON responses come from an API, dates are serialized as ISO strings. This utility converts specified fields back to JavaScript Date objects, enabling proper date comparisons in assertions.

Step 6: Create Error Helper Functions

Create tests/errors.ts with factory functions for creating expected error responses:

import { ProblemDocument } from 'http-problem-details';
import { StatusCodes } from 'http-status-codes';

export const emptyText = '';

export const bigText = (length: number = 256): string => {
  return 'a'.repeat(length);
};

const tooBigString = (maxLength: number): string =>
  `Too big: expected string to have <=${maxLength} characters`;

const tooSmallString = (minLength: number): string =>
  `Too small: expected string to have >=${minLength} characters`;

export type ValidationError = {
  path: string;
  message: string;
  code: string;
};

export const createValidationError = (
  errors: ValidationError[]
): ProblemDocument => {
  return new ProblemDocument(
    {
      detail: 'The request contains invalid data',
      status: StatusCodes.BAD_REQUEST,
    },
    { errors }
  );
};

export const validationError = {
  tooSmall: (path: string, minLength: number): ValidationError => ({
    path,
    message: tooSmallString(minLength),
    code: 'too_small',
  }),
  tooBig: (path: string, maxLength: number): ValidationError => ({
    path,
    message: tooBigString(maxLength),
    code: 'too_big',
  }),
  requiredString: (path: string): ValidationError => ({
    path,
    message: 'Invalid input: expected string, received undefined',
    code: 'invalid_type',
  }),
  invalidUrl: (path: string): ValidationError => ({
    path,
    message: 'Invalid URL',
    code: 'invalid_format',
  }),
  invalidUuid: (path: string): ValidationError => ({
    path,
    message: 'Invalid UUID',
    code: 'invalid_format',
  }),
  notPositive: (path: string): ValidationError => ({
    path,
    message: 'Too small: expected number to be >0',
    code: 'too_small',
  }),
  requiredNumber: (path: string): ValidationError => ({
    path,
    message: 'Invalid input: expected number, received undefined',
    code: 'invalid_type',
  }),
};

export const createNotFoundError = (detail: string): ProblemDocument => {
  return new ProblemDocument({
    detail,
    status: StatusCodes.NOT_FOUND,
  });
};

Let's break down what each part does:

• emptyText and bigText(): Generate test data for boundary validation (empty strings and strings exceeding maximum length).

• ValidationError type: Matches the structure returned by Zod validation errors.

• createValidationError(): Constructs a ProblemDocument (RFC 7807 standard for HTTP API errors) with validation errors.

• validationError object: Factory methods for each validation error type, ensuring test expectations match actual API messages.

• createNotFoundError(): Creates expected 404 responses for resource-not-found scenarios.

Step 7: Create Custom Assertion Helpers

Create tests/assertions.ts with fluent assertion builders:

import assert from 'node:assert';
import { ProblemDocument } from 'http-problem-details';
import type { Page } from '@/types/pagination.js';

export const assertPage = <TResult>(page: Page<TResult>) => {
  return {
    hasItemsCountAtLeast(expected: number) {
      assert.ok(page);
      assert.ok(
        page.items.length >= expected,
        `Expected at least ${expected} items, got ${page.items.length}`
      );
      return this;
    },
    hasItemsCount(expected: number) {
      assert.ok(page);
      assert.strictEqual(
        page.items.length,
        expected,
        `Expected ${expected} items, got ${page.items.length}`
      );
      return this;
    },
    hasTotalCount(expected: number) {
      assert.ok(page);
      assert.strictEqual(
        page.totalCount,
        expected,
        `Expected totalCount to be ${expected}, got ${page.totalCount}`
      );
      return this;
    },
    hasTotalPages(expected: number) {
      assert.ok(page);
      assert.strictEqual(
        page.totalPages,
        expected,
        `Expected totalPages to be ${expected}, got ${page.totalPages}`
      );
      return this;
    },
    hasEmptyResult() {
      return this.hasItemsCount(0).hasTotalCount(0).hasTotalPages(0);
    },
  };
};

export const assertStrictEqualProblemDocument = (
  actual: ProblemDocument,
  expected: ProblemDocument
): void => {
  assert.strictEqual(actual.status, expected.status);
  assert.strictEqual(actual.detail, expected.detail);
  if ('errors' in actual && 'errors' in expected) {
    assert.deepStrictEqual(actual['errors'], expected['errors']);
  }
};

The fluent interface pattern enables chainable assertions that read like natural language:

assertPage(page)
  .hasItemsCount(10)
  .hasTotalCount(50)
  .hasTotalPages(5);

Key Benefits:

• Readability: Assertions read like specifications

• Chainability: Multiple assertions in one statement

• Custom messages: Clear failure messages aid debugging

Step 8: Understanding Hono's testClient

Before building the DSL, let's understand the core testing utility we'll use. Hono provides a built-in testClient function from hono/testing that wraps our routes and provides a type-safe interface to make requests without spinning up an actual HTTP server.

Key Features

1. No Server Required: Executes requests in-memory, making tests faster and more reliable

2. Full Type Safety: The client is automatically typed based on our route definitions:

    // TypeScript knows exactly what parameters this endpoint accepts
    const response = await client.stores.$post({
      json: { name: 'Walmart', url: 'https://walmart.com' }
    });
   

3. Route-Aware API: The client mirrors our route structure:

    // GET /stores/:storeId
    await client.stores[':storeId'].$get({
      param: { storeId: '123' }
    });
   
    // POST /products/:productId/prices
    await client.products[':productId'].prices.$post({
      param: { productId: '456' },
      json: { price: 99.99 }
    });
   

4. Query Parameter Support:

    await client.stores.$get({
      query: { pageNumber: '1', pageSize: '10', name: 'walmart' }
    });
   

Why testClient Over Supertest or Fetch?

Step 9: Build the Stores DSL

Now let's build the Domain-Specific Language for store operations. Create tests/stores/stores-dsl.ts:

Part 1: Imports and Test Data Factories

import { testClient } from 'hono/testing';
import { type AddStore } from '@/features/stores/add-store.js';
import { storeRoute } from '@/features/stores/index.js';
import type { ProblemDocument } from 'http-problem-details/dist/ProblemDocument.js';
import { type Store } from '@/features/stores/store.js';
import { faker } from '@faker-js/faker';
import { StatusCodes } from 'http-status-codes';
import assert from 'node:assert';
import { assertStrictEqualProblemDocument } from '../assertions.js';
import type { EditStore } from '@/features/stores/edit-store.js';
import type { ListStores } from '@/features/stores/list-stores.js';
import type { Page } from '@/types/pagination.js';

export const wallmart = (overrides?: Partial<AddStore>): AddStore => {
  return {
    name: `wallmart ${faker.string.uuid()}`,
    url: 'https://www.walmart.com',
    ...overrides,
  };
};

export const nike = (overrides?: Partial<AddStore>): AddStore => {
  return {
    name: `nike ${faker.string.uuid()}`,
    url: 'https://www.nike.com',
    ...overrides,
  };
};

Factory functions create test data with:

• Unique names: Using faker.string.uuid() prevents collision between tests.

• Sensible defaults: Valid data by default.

• Override capability: Spread operator allows partial customization for specific test scenarios.

Part 2: Add Store Operation

export async function addStore(input: AddStore): Promise<Store>;
export async function addStore(
  input: AddStore,
  expectedProblemDocument: ProblemDocument
): Promise<ProblemDocument>;

export async function addStore(
  input: AddStore,
  expectedProblemDocument?: ProblemDocument
): Promise<Store | ProblemDocument> {
  const client = testClient(storeRoute);
  const response = await client.stores.$post({
    json: input,
  });

  if (response.status === StatusCodes.CREATED) {
    assert.ok(
      !expectedProblemDocument,
      'Expected a problem document but received CREATED status'
    );
    const store = await response.json();
    assert.ok(store);
    return store;
  } else {
    const problemDocument = await response.json();
    assert.ok(problemDocument);
    assert.ok(
      expectedProblemDocument,
      `Expected CREATED status but received ${response.status}`
    );
    assertStrictEqualProblemDocument(problemDocument, expectedProblemDocument);
    return problemDocument;
  }
}

Key Design Decisions:

1. TypeScript Overloads: Two signatures provide type safety:

   • Without error expectation → returns Store

   • With error expectation → returns ProblemDocument

2. Dual-mode behavior: The function both executes the request AND validates expectations, reducing boilerplate in tests

3. Clear assertions: If we expect success but get an error (or vice versa), the test fails with a descriptive message

Part 3: Edit Store Operation

export async function editStore(
  storeId: string,
  input: AddStore
): Promise<Store>;
export async function editStore(
  storeId: string,
  input: AddStore,
  expectedProblemDocument: ProblemDocument
): Promise<ProblemDocument>;
export async function editStore(
  storeId: string,
  input: EditStore,
  expectedProblemDocument?: ProblemDocument
): Promise<Store | ProblemDocument> {
  const client = testClient(storeRoute);
  const response = await client.stores[':storeId'].$put({
    param: { storeId },
    json: input,
  });

  if (response.status === StatusCodes.OK) {
    const store = await response.json();
    assert.ok(store);
    return store;
  } else {
    const problemDocument = await response.json();
    assert.ok(problemDocument);
    if (expectedProblemDocument) {
      assertStrictEqualProblemDocument(
        problemDocument,
        expectedProblemDocument
      );
    }
    return problemDocument;
  }
}

Note the route path syntax: client.stores[':storeId'].$put() mirrors the Hono route definition /stores/:storeId.

Part 4: Get Store Operation

export async function getStore(storeId: string): Promise<Store>;
export async function getStore(
  storeId: string,
  expectedProblemDocument: ProblemDocument
): Promise<ProblemDocument>;

export async function getStore(
  storeId: string,
  expectedProblemDocument?: ProblemDocument
): Promise<Store | ProblemDocument> {
  const client = testClient(storeRoute);
  const response = await client.stores[':storeId'].$get({
    param: { storeId },
  });

  if (response.status === StatusCodes.OK) {
    const store = await response.json();
    assert.ok(store);
    return store;
  } else {
    const problemDocument = await response.json();
    assert.ok(problemDocument);
    if (expectedProblemDocument) {
      assertStrictEqualProblemDocument(
        problemDocument,
        expectedProblemDocument
      );
    }
    return problemDocument;
  }
}

Part 5: List Stores Operation

export async function listStores(params: ListStores): Promise<Page<Store>>;
export async function listStores(
  params: ListStores,
  expectedProblemDocument: ProblemDocument
): Promise<ProblemDocument>;

export async function listStores(
  params: ListStores,
  expectedProblemDocument?: ProblemDocument
): Promise<Page<Store> | ProblemDocument> {
  const client = testClient(storeRoute);
  const queryParams = {
    pageNumber: params.pageNumber?.toString(),
    pageSize: params.pageSize?.toString(),
    name: params.name,
  };
  const response = await client.stores.$get({
    query: queryParams,
  });

  if (response.status === StatusCodes.OK) {
    const page = await response.json();
    assert.ok(page);
    return page;
  } else {
    const problemDocument = await response.json();
    assert.ok(problemDocument);
    if (expectedProblemDocument) {
      assertStrictEqualProblemDocument(
        problemDocument,
        expectedProblemDocument
      );
    }
    return problemDocument;
  }
}

Note how listStores converts numeric parameters to strings, query parameters are always strings in HTTP.

Part 6: Store Assertions

export const assertStore = (store: Store) => {
  return {
    hasName(expected: string) {
      assert.strictEqual(
        store.name,
        expected,
        `Expected name to be ${expected}, got ${store.name}`
      );
      return this;
    },
    hasUrl(expected: string) {
      assert.strictEqual(
        store.url,
        expected,
        `Expected url to be ${expected}, got ${store.url}`
      );
      return this;
    },
    hasStoreId(expected: string) {
      assert.strictEqual(
        store.storeId,
        expected,
        `Expected storeId to be ${expected}, got ${store.storeId}`
      );
      return this;
    },
    isTheSameOf(expected: Store) {
      return this.hasStoreId(expected.storeId)
        .hasName(expected.name)
        .hasUrl(expected.url);
    },
  };
};

The isTheSameOf method is particularly useful for verifying that retrieved entities match created ones.

Step 10: Write Store Tests

Now let's create the test files using our DSL.

Add Store Tests

Create tests/stores/add-store.test.ts:

import { test, describe } from 'node:test';
import { addStore, assertStore, wallmart } from './stores-dsl.js';
import {
  emptyText,
  bigText,
  createValidationError,
  validationError,
} from '../errors.js';

describe('Add Store Endpoint', () => {
  test('should create a new store with valid data', async () => {
    const input = wallmart();
    const store = await addStore(input);
    assertStore(store).hasName(input.name).hasUrl(input.url);
  });

  describe('Property validations', () => {
    const testCases = [
      {
        name: 'should reject empty store name',
        input: wallmart({ name: emptyText }),
        expectedError: createValidationError([
          validationError.tooSmall('name', 1),
        ]),
      },
      {
        name: 'should reject store name longer than 1024 characters',
        input: wallmart({ name: bigText(1025) }),
        expectedError: createValidationError([
          validationError.tooBig('name', 1024),
        ]),
      },
      {
        name: 'should reject missing store name',
        input: wallmart({ name: undefined }),
        expectedError: createValidationError([
          validationError.requiredString('name'),
        ]),
      },
      {
        name: 'should reject empty store URL',
        input: wallmart({ url: emptyText }),
        expectedError: createValidationError([
          validationError.invalidUrl('url'),
        ]),
      },
      {
        name: 'should reject invalid URL format',
        input: wallmart({ url: 'not-a-valid-url' }),
        expectedError: createValidationError([
          validationError.invalidUrl('url'),
        ]),
      },
      {
        name: 'should reject URL longer than 2048 characters',
        input: wallmart({
          url: `https://www.walmart.com/${bigText(2048)}`,
        }),
        expectedError: createValidationError([
          validationError.tooBig('url', 2048),
        ]),
      },
      {
        name: 'should reject missing URL',
        input: wallmart({ url: undefined }),
        expectedError: createValidationError([
          validationError.requiredString('url'),
        ]),
      },
    ];

    for (const { name, input, expectedError } of testCases) {
      test(name, async () => {
        await addStore(input, expectedError);
      });
    }
  });
});

Key Patterns:

• Data-driven tests: The testCases array with loop pattern avoids repetitive test code.

• Descriptive names: Each test case has a clear name describing what it validates.

• Clean DSL usage: addStore(input, expectedError) reads naturally.

Edit Store Tests

Create tests/stores/edit-store.test.ts:

import { test, describe } from 'node:test';
import {
  addStore,
  editStore,
  wallmart,
  nike,
  assertStore,
} from './stores-dsl.js';
import { type Store } from '@/features/stores/store.js';
import {
  emptyText,
  bigText,
  createValidationError,
  validationError,
  createNotFoundError,
} from '../errors.js';
import type { EditStore } from '@/features/stores/edit-store.js';

describe('Edit Store Endpoint', () => {
  test('should edit an existing store with valid data', async () => {
    const store = await addStore(wallmart());
    const input = nike();
    const newStore = await editStore(store.storeId, input);
    assertStore(newStore).hasName(input.name).hasUrl(input.url);
  });

  describe('Property validations', async () => {
    const testCases = [
      {
        name: 'should reject empty store name',
        input: (store: Store) => ({ name: emptyText, url: store.url }),
        expectedError: createValidationError([
          validationError.tooSmall('name', 1),
        ]),
      },
      {
        name: 'should reject store name longer than 1024 characters',
        input: (store: Store) => ({ name: bigText(1025), url: store.url }),
        expectedError: createValidationError([
          validationError.tooBig('name', 1024),
        ]),
      },
      {
        name: 'should reject missing store name',
        input: (store: Store) => ({ url: store.url }) as EditStore,
        expectedError: createValidationError([
          validationError.requiredString('name'),
        ]),
      },
      {
        name: 'should reject empty store URL',
        input: (store: Store) => ({ name: store.name, url: emptyText }),
        expectedError: createValidationError([
          validationError.invalidUrl('url'),
        ]),
      },
      {
        name: 'should reject invalid URL format',
        input: (store: Store) => ({ name: store.name, url: 'not-a-valid-url' }),
        expectedError: createValidationError([
          validationError.invalidUrl('url'),
        ]),
      },
      {
        name: 'should reject URL longer than 2048 characters',
        input: (store: Store) => ({
          name: store.name,
          url: `https://www.walmart.com/${bigText(2048)}`,
        }),
        expectedError: createValidationError([
          validationError.tooBig('url', 2048),
        ]),
      },
      {
        name: 'should reject missing URL',
        input: (store: Store) => ({ name: store.name }) as EditStore,
        expectedError: createValidationError([
          validationError.requiredString('url'),
        ]),
      },
    ];

    for (const { name, input, expectedError } of testCases) {
      test(name, async () => {
        const store = await addStore(wallmart());
        await editStore(store.storeId, input(store), expectedError);
      });
    }
  });

  test('should return 404 for non-existent store', async () => {
    const nonExistentId = '01940b6d-1234-7890-abcd-ef1234567890';
    await editStore(
      nonExistentId,
      nike(),
      createNotFoundError(`Store ${nonExistentId} not found`)
    );
  });

  test('should reject invalid UUID format', async () => {
    await editStore(
      'invalid-uuid',
      nike(),
      createValidationError([validationError.invalidUuid('storeId')])
    );
  });
});

Notable Details:

• Test cases use a function (store: Store) => {...} to construct input based on an existing store.

• Each validation test creates fresh data to ensure test isolation.

• Edge cases (404, invalid UUID) are tested explicitly.

Get Store Tests

Create tests/stores/get-store.test.ts:

import { test, describe } from 'node:test';
import { addStore, assertStore, getStore, wallmart } from './stores-dsl.js';
import {
  createNotFoundError,
  createValidationError,
  validationError,
} from '../errors.js';

describe('Get Store Endpoint', () => {
  test('should get an existing store by ID', async () => {
    const createdStore = await addStore(wallmart());
    const retrievedStore = await getStore(createdStore.storeId);
    assertStore(retrievedStore).isTheSameOf(createdStore);
  });

  test('should return 404 for non-existent store', async () => {
    const nonExistentId = '01940b6d-1234-7890-abcd-ef1234567890';
    await getStore(
      nonExistentId,
      createNotFoundError(`Store ${nonExistentId} not found`)
    );
  });

  test('should reject invalid UUID format', async () => {
    await getStore(
      'invalid-uuid',
      createValidationError([validationError.invalidUuid('storeId')])
    );
  });

  test('should reject empty storeId', async () => {
    await getStore(
      '',
      createValidationError([validationError.invalidUuid('storeId')])
    );
  });
});

The isTheSameOf assertion makes the retrieval test extremely readable.

List Stores Tests

Create tests/stores/list-stores.test.ts:

import { test, describe } from 'node:test';
import { addStore, assertStore, listStores, wallmart } from './stores-dsl.js';
import { assertPage } from '../assertions.js';

describe('List Stores Endpoint', () => {
  test('should filter stores by name', async () => {
    const store = await addStore(wallmart());

    const page = await listStores({
      name: store.name,
      pageSize: 10,
      pageNumber: 1,
    });

    assertPage(page).hasItemsCount(1);
    assertStore(page.items[0]).isTheSameOf(store);
  });

  test('should return empty items when no stores match filter', async () => {
    const page = await listStores({
      name: 'nonexistent-store-xyz',
      pageSize: 10,
      pageNumber: 1,
    });

    assertPage(page).hasEmptyResult();
  });
});

The unique store names generated by faker.string.uuid() ensure that filtering by name returns exactly the expected store.

Step 11: Run the Tests

With everything in place, run the test suite:

npm test

We should see output similar to:

▶ Add Store Endpoint
  ✔ should create a new store with valid data
  ▶ Property validations
    ✔ should reject empty store name
    ✔ should reject store name longer than 1024 characters
    ...
▶ Edit Store Endpoint
  ✔ should edit an existing store with valid data
  ...

Best Practices Summary

1. Use Hono's testClient: It provides type-safe testing without running a server, making tests fast and reliable.

2. Generate unique test data with Faker: Use @faker-js/faker to create unique identifiers and realistic data that prevents test collisions.

3. Create a DSL for our domain: Encapsulate API interactions in reusable functions that handle both success and error paths.

4. Use TypeScript overloads: Provide different return types based on whether an error is expected, improving type safety in tests.

5. Use fluent assertions: They improve readability and make failures easier to diagnose.

6. Data-driven validation tests: Loop through test cases to avoid repetitive test code.

7. Test edge cases explicitly: Invalid UUIDs, empty strings, non-existent resources, and boundary conditions should all have tests.

8. Verify side effects: When an operation affects related entities (like price history affecting product's current price), verify those changes.

9. Clean up resources: Use global teardown to close database connections.

10. Structure tests logically: Group by endpoint/feature, with happy path first, then validation, then edge cases.

Common Mistakes to Avoid

1. Not parsing dates from JSON: Leads to string/Date comparison failures.

2. Using static test data: Causes flaky tests in shared databases.

3. Forgetting to await async operations: Results in tests passing incorrectly.

4. Over-mocking: Integration tests should use real database operations when possible.

5. Not testing error responses thoroughly: Validation errors should verify status, message, and error details.

6. Starting an HTTP server for tests: Use testClient instead for faster, more reliable tests.

You can find all the code here. Thanks, and happy coding.

We'll build upon an existing Hono application, implementing a complete data layer using Drizzle ORM with PostgreSQL. By the end, we will understand how to leverage Drizzle's type-safe query builder and schema management to create production-ready APIs.

What is Drizzle?

Drizzle is a TypeScript-first Object-Relational Mapping library designed with performance and developer experience as primary concerns. Unlike traditional ORMs that abstract SQL away entirely, Drizzle takes a different approach: it provides a thin, type-safe layer over SQL that feels natural to developers who understand relational databases. Drizzle follows several core design principles that distinguish it from other ORMs:

• SQL-like API: Query builders mirror SQL syntax closely rather than hiding it.

• Type Safety: Full TypeScript type inference from schema to query results.

• Zero Dependencies: Core package has no runtime dependencies.

• Database Agnostic Drivers: All database drivers are optional peer dependencies.

• Thin Abstraction Layer: Minimal runtime overhead, direct SQL generation.

Why Drizzle for Hono?

Hono is designed to be lightweight and fast, making it perfect for edge computing. Drizzle shares this philosophy, providing a minimal footprint while maintaining full type safety. Together, they create an optimal stack for modern API development.

Creating a PostgreSQL Database

We will use Docker to create our local database. Create the docker-compose.yml file with the following content:

services:
  database:
    image: postgres
    ports:
      - '5432:5432'
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: myuser
      POSTGRES_PASSWORD: mypassword

Then, add the following scripts to the package.json file:

{
  ...
  "scripts": {
    ...
    "database:up": "docker-compose up database -d",
    "database:down": "docker-compose down database",
    "database:stop": "docker-compose stop database",
  },
...
}

Execute npm run database:up to start up the database.

Creating a Database Connection

Install the following packages:

npm install drizzle-orm 
npm install pg
npm install drizzle-kit

First, we need to configure our database connection string. In the env.ts file, we've already defined the environment schema:

import { config } from 'dotenv';
import { expand } from 'dotenv-expand';
import { ZodError, z } from 'zod';

const ENVSchema = z.object({
  NODE_ENV: z
    .enum(['development', 'production', 'test'])
    .default('development'),
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string(),
  TOKEN: z.string().optional(),
});

expand(config());

try {
  ENVSchema.parse(process.env);
} catch (error) {
  if (error instanceof ZodError) {
    const e = new Error(
      `Environment validation failed:\n ${z.treeifyError(error)}`
    );
    e.stack = '';
    throw e;
  } else {
    console.error('Unexpected error during environment validation:', error);
    throw error;
  }
}

export const ENV = ENVSchema.parse(process.env);

This validates that DATABASE_URL is present at startup, preventing runtime errors from missing configuration. The database client is initialized in the database/client.ts file:

import { drizzle } from 'drizzle-orm/node-postgres';
import * as schema from './schemas.js';
import { ENV } from '@/env.js';
export const client = drizzle(ENV.DATABASE_URL, {
  schema,
  logger: ENV.NODE_ENV === 'development',
});

• Connection String: We use drizzle-orm/node-postgres, which accepts a connection string directly.

• Schema Import: All schemas are passed to enable type-safe queries with relations.

• Query Logging: Enabled in development to see generated SQL queries.

• Single Instance: This client is exported and reused throughout the application.

Schema Definition

Drizzle schemas define our database structure using TypeScript. They serve as both the source of truth for our database and the foundation for type inference. The Drizzle stores schema is defined in the features/stores/store.ts file:

import { z } from 'zod';
import { varchar, pgSchema, uuid } from 'drizzle-orm/pg-core';

export const storeSchema = z.object({
  storeId: z.uuidv7(),
  name: z.string().min(1).max(1024),
  url: z.url().max(2048),
});

export type Store = z.infer<typeof storeSchema>;

const dbSchema = pgSchema('price_tracker');

export const stores = dbSchema.table('stores', {
  storeId: uuid('storeid').primaryKey(),
  name: varchar('name', { length: 1024 }).notNull(),
  url: varchar('url', { length: 2048 }).notNull(),
});

Drizzle core features:

• pgSchema: Creates a PostgreSQL schema to organize tables.

• table: Defines a table within the schema.

• Column Types: Type-safe column definitions (uuid, varchar, numeric, timestamp).

• Constraints: Primary keys, not null, default values.

The Drizzle products schema in features/stores/product.ts demonstrates more complex features:

import { z } from 'zod';
import {
  varchar,
  pgSchema,
  uuid,
  numeric,
  timestamp,
} from 'drizzle-orm/pg-core';
import { stores } from '@/features/stores/store.js';

export const productSchema = z.object({
  storeId: z.uuidv7(),
  productId: z.uuidv7(),
  name: z.string().min(1).max(1024),
  url: z.url().max(2048),
  currentPrice: z.number().positive().nullable(),
  priceChangePercentage: z.number().nullable(),
  lastUpdated: z.coerce.date().nullable(),
  currency: z.string().length(3),
});

export type Product = z.infer<typeof productSchema>;

const dbSchema = pgSchema('price_tracker');

export const products = dbSchema.table('products', {
  productId: uuid('productid').primaryKey(),
  storeId: uuid('storeid')
    .notNull()
    .references(() => stores.storeId),
  name: varchar('name', { length: 1024 }).notNull(),
  url: varchar('url', { length: 2048 }).notNull(),
  currentPrice: numeric('currentprice', {
    precision: 10,
    scale: 2,
    mode: 'number',
  }),
  priceChangePercentage: numeric('pricechangepercentage', {
    precision: 5,
    scale: 2,
    mode: 'number',
  }),
  lastUpdated: timestamp('lastupdated', { mode: 'date' }),
  currency: varchar('currency', { length: 3 }).notNull(),
});

export const priceHistorySchema = z.object({
  productId: z.uuidv7(),
  priceHistoryId: z.uuidv7(),
  timestamp: z.coerce.date(),
  price: z.number().positive(),
});

export type PriceHistory = z.infer<typeof priceHistorySchema>;

export const priceHistories = dbSchema.table('price_histories', {
  priceHistoryId: uuid('pricehistoryid').primaryKey(),
  productId: uuid('productid')
    .notNull()
    .references(() => products.productId),
  timestamp: timestamp('timestamp', { mode: 'date' }).notNull(),
  price: numeric('price', {
    precision: 10,
    scale: 2,
    mode: 'number',
  }).notNull(),
});

Drizzle advanced features:

• Foreign Keys: .references(() => stores.storeId) creates a relationship.

• Numeric Types: precision and scale define decimal precision.

• Timestamp Modes: mode: 'date' returns JavaScript Date objects.

• Number Modes: mode: 'number' returns a number.

• Nullable Fields: Fields without .notNull() are nullable by default.

All schemas are exported from the database/schemas.ts file:

export { stores } from '@/features/stores/store.js';
export { products, priceHistories } from '@/features/products/product.js';

This centralized export is imported by the database client, enabling Drizzle to understand relationships between tables.

Migrations

Drizzle Kit generates and manages database migrations automatically from our schema definitions. The migration configuration is defined in the drizzle.config.ts file:

import { ENV } from './src/env.js';
import { defineConfig } from 'drizzle-kit';
export default defineConfig({
  out: './src/database/migrations',
  schema: './src/database/schemas.ts',
  dialect: 'postgresql',
  dbCredentials: {
    url: ENV.DATABASE_URL,
  },
  migrations: {
    schema: 'price_tracker',
  },
});

The configuration options are:

• out: Directory where migration files are generated.

• schema: Path to our schema definitions.

• dialect: Database type (postgresql, mysql, sqlite).

• dbCredentials: Connection information.

• migrations.schema: PostgreSQL schema name for migrations table.

The package.json file includes scripts for migration management:

{
  ...
  "scripts": {
    ...
    "database:generate": "tsx ./node_modules/drizzle-kit/bin.cjs generate",
    "database:migrate": "tsx ./node_modules/drizzle-kit/bin.cjs migrate",
    "database:studio": "tsx ./node_modules/drizzle-kit/bin.cjs studio"
  },
...
}

Drizzle Kit cannot properly handle path aliases or file extensions (in certain TypeScript configurations) because it uses esbuild-register. This library has limited module resolution capabilities compared to the full TypeScript compiler. Due to this issue, we use tsx to run Drizzle-kit instead of the regular command drizzle-kit generate and drizzle-kit migrate.

The workflow to use Drizzle-kit could be something like:

• Define or modify schemas in our TypeScript files.

• Generate migration: npm run database:generate.

• Review the SQL in the generated migration file.

• Apply migration: npm run database:migrate.

drizzle-kit studio command spins up a server for Drizzle Studio(SQL database explorer) hosted on https://local.drizzle.studio

Generated migrations are stored in the database/migrations folders. Drizzle Kit also maintains metadata in the database/migrations/meta folder to track migration history and generate incremental changes.

Querying with Drizzle

In Drizzle ORM, we have two query styles.

SQL-like queries

These are explicit, low-level, SQL-shaped queries. They map very closely to real SQL and give us full control over joins, filters, grouping, and projections.

const result = await db
  .select({
    userId: users.id,
    userName: users.name,
    postTitle: posts.title,
  })
  .from(users)
  .leftJoin(posts, eq(posts.userId, users.id))
  .where(eq(users.active, true));

I want to write SQL, but safely.

Relational queries

Relational queries are higher-level and schema-aware. We define relations once in our schema, and Drizzle automatically figures out what to do.

const result = await db.query.users.findMany({
  where: (users, { eq }) => eq(users.active, true),
  with: {
    posts: {
      columns: {
        id: true,
        title: true,
      },
    },
  },
});

I want objects. Drizzle figures out the joins.

Let's see how to integrate Drizzle in our application using the low-level API.

Insert Statement

Update the file features/stores/add-store.ts file with the following content:

import { Hono } from 'hono';
import { v7 } from 'uuid';
import { StatusCodes } from 'http-status-codes';
import { stores, storeSchema } from './store.js';
import { zValidator } from '@/utils/validation.js';
import { client } from '@/database/client.js';

const schema = storeSchema.omit({ storeId: true });

export const addRoute = new Hono().post(
  '/',
  zValidator('json', schema),
  async c => {
    const data = c.req.valid('json');
    const [store] = await client
      .insert(stores)
      .values({ ...data, storeId: v7() })
      .returning();
    return c.json(store, StatusCodes.CREATED);
  }
);

• Insert Operation: The .insert(stores) method initiates an insert query on the stores table.

• Values Method: .values() accepts an object matching the table schema, providing type safety.

• UUID Generation: Uses UUID v7 for time-sortable unique identifiers.

• Returning Clause: .returning() is a PostgreSQL feature that returns the inserted record, eliminating the need for a separate SELECT query.

• Type Safety: TypeScript ensures that the data object contains all required fields with correct types.

Select Statement

Update the file feature/stores/get-store.ts file with the following content:

import { Hono } from 'hono';
import { stores, storeSchema } from './store.js';
import { StatusCodes } from 'http-status-codes';
import { zValidator } from '@/utils/validation.js';
import { createResourceNotFoundPD } from '@/utils/problem-document.js';
import { client } from '@/database/client.js';
import { eq } from 'drizzle-orm';

const schema = storeSchema.pick({ storeId: true });

export const getRoute = new Hono().get(
  '/:storeId',
  zValidator('param', schema),
  async c => {
    const { storeId } = c.req.valid('param');
    const [store] = await client
      .select()
      .from(stores)
      .where(eq(stores.storeId, storeId))
      .limit(1);
    if (!store) {
      return c.json(
        createResourceNotFoundPD(c.req.path, `Store ${storeId} not found`),
        StatusCodes.NOT_FOUND
      );
    }
    return c.json(store, StatusCodes.OK);
  }
);

• Selective Operation: .select() without arguments retrieves all columns, but Drizzle supports selective column retrieval.

• Primary Key Lookup: Using eq() on the primary key ensures an index is used, providing O(1) lookup performance.

• Limit Clause: .limit(1) tells the database to stop scanning after finding the first match.

• Null Handling: The query returns an array; checking if (!store) handles the not-found case gracefully.

Update the features/stores/list-stores.ts file with the following content:

import { Hono } from 'hono';
import { stores } from './store.js';
import { StatusCodes } from 'http-status-codes';
import { paginationSchema, createPage } from '@/types/pagination.js';
import { z } from 'zod';
import { zValidator } from '@/utils/validation.js';
import { client } from '@/database/client.js';
import { like, count, SQL, and } from 'drizzle-orm';

const schema = paginationSchema.extend({
  name: z.string().optional(),
});

export const listRoute = new Hono().get(
  '/',
  zValidator('query', schema),
  async c => {
    const { pageNumber, pageSize, name } = c.req.valid('query');
    const filters: SQL[] = [];
    const offset = (pageNumber - 1) * pageSize;
    if (name) filters.push(like(stores.name, `%${name}%`));

    const [{ totalCount }] = await client
      .select({ totalCount: count() })
      .from(stores)
      .where(and(...filters));

    const items = await client
      .select()
      .from(stores)
      .where(and(...filters))
      .limit(pageSize)
      .offset(offset);
    return c.json(
      createPage(items, totalCount, pageNumber, pageSize),
      StatusCodes.OK
    );
  }
);

• Aggregate Functions: count() provides SQL COUNT functionality with type safety.

• LIKE Operator: The like() function enables pattern matching for text search.

• Filtering: Building a filter array allows conditional query construction.

• Logical Operators: and(...filters) combines multiple conditions with AND logic.

• Pagination: .limit() and .offset() implement cursor-based pagination.

• Two-Query Pattern: Separate queries for count and data retrieval ensure accurate pagination metadata.

Update Statement

Navigate to the features/stores/edit-store.ts file and update the content with:

import { Hono } from 'hono';
import { StatusCodes } from 'http-status-codes';
import { stores, storeSchema } from './store.js';
import { zValidator } from '@/utils/validation.js';
import { createResourceNotFoundPD } from '@/utils/problem-document.js';
import { client } from '@/database/client.js';
import { eq } from 'drizzle-orm';

const paramSchema = storeSchema.pick({ storeId: true });
const bodySchema = storeSchema.pick({ name: true, url: true });

export const editRoute = new Hono().put(
  '/:storeId',
  zValidator('param', paramSchema),
  zValidator('json', bodySchema),
  async c => {
    const { storeId } = c.req.valid('param');
    const data = c.req.valid('json');
    const existing = await client
      .select()
      .from(stores)
      .where(eq(stores.storeId, storeId))
      .limit(1);

    if (existing.length === 0) {
      return c.json(
        createResourceNotFoundPD(c.req.path, `Store ${storeId} not found`),
        StatusCodes.NOT_FOUND
      );
    }
    const [store] = await client
      .update(stores)
      .set(data)
      .where(eq(stores.storeId, storeId))
      .returning();
    return c.json(store, StatusCodes.OK);
  }
);

• Select Query: .select().from(stores) creates a SELECT statement with full type inference.

• Where Clauses: The eq() operator provides type-safe equality comparisons.

• Existence Check: Queries the database to verify the resource exists before attempting updates.

• Update Operation: .update(stores).set(data) initiates an update query.

• Conditional Updates: The .where() clause ensures only the specific record is modified.

This endpoint follows a check-then-update pattern. While this involves two database round-trips, it provides better error handling and user feedback.

Drizzle ORM provides a type-safe, lightweight solution for database operations in Hono applications. Its SQL-like API, excellent TypeScript integration, and minimal runtime overhead make it ideal for modern web applications. You can find all the code here. Thanks, and happy coding.

RFC 7807: Problem Details for HTTP APIs

The RFC 7807 standard defines a problem detail format for HTTP API errors. This specification provides a consistent, machine-readable way to express error information.

• type: A URI reference identifying the problem type.

• title: A short, human-readable summary.

• status: The HTTP status code.

• detail: A human-readable explanation specific to this occurrence.

• instance: A URI reference identifying the occurrence.

Let’s start the implementation of the standard by installing the following package:

npm install http-problem-details

Create the utils/problem-document.ts file with the following content:

import { ProblemDocument } from 'http-problem-details';
import { StatusCodes } from 'http-status-codes';
import { z } from 'zod';
import { ENV } from '@/env.js';

export const createResourceNotFoundPD = (path: string, detail: string) => {
  return new ProblemDocument({
    type: '/problems/resource-not-found',
    title: 'Resource not found',
    status: StatusCodes.NOT_FOUND,
    detail: detail,
    instance: path,
  });
};

export const createInternalServerErrorPD = (path: string, error?: Error) => {
  const extensions =
    ENV.NODE_ENV === 'development' && error?.stack
      ? { stack: error.stack }
      : undefined;

  return new ProblemDocument(
    {
      type: '/problems/internal-server-error',
      title: 'Internal Server Error',
      status: StatusCodes.INTERNAL_SERVER_ERROR,
      detail: 'An unexpected error occurred',
      instance: path,
    },
    extensions
  );
};

export const createValidationErrorPD = (
  path: string,
  issues: z.core.$ZodIssue[]
) => {
  return new ProblemDocument(
    {
      type: '/problems/validation-error',
      title: 'Validation Error',
      status: StatusCodes.BAD_REQUEST,
      detail: 'The request contains invalid data',
      instance: path,
    },
    {
      errors: issues.map(err => ({
        path: err.path.join('.'),
        message: err.message,
        code: err.code,
      })),
    }
  );
};

The methods above help us create the ProblemDocument objects that we will use across our project. The method createResourceNotFoundPD is used within route handlers to indicate specific resources were not found. For example, the features/stores/get-store.ts file has the following content:

import { Hono } from 'hono';
import { stores, storeSchema } from './store.js';
import { StatusCodes } from 'http-status-codes';
import { zValidator } from '@/utils/validation.js';
import { createResourceNotFoundPD } from '@/utils/problem-document.js';

const schema = storeSchema.pick({ storeId: true });

export const getRoute = new Hono().get(
  '/:storeId',
  zValidator('param', schema),
  async c => {
    const { storeId } = c.req.valid('param');
    const store = stores.find(s => s.storeId === storeId);
    if (!store) {
      return c.json(
        createResourceNotFoundPD(c.req.path, `Store ${storeId} not found`),
        StatusCodes.NOT_FOUND
      );
    }
    return c.json(store, StatusCodes.OK);
  }
);

This ensures consistency between route-level 404s. For validation failures, the createValidationErrorPD implementation extends the ProblemDetails object with additional error context from Zod. To complete the integration, the zValidator method provides a hook to customize error responses. Create the utils/validation.ts file with the following content:

import { type ZodSchema } from 'zod';
import type { ValidationTargets } from 'hono';
import { zValidator as zv } from '@hono/zod-validator';
import { StatusCodes } from 'http-status-codes';
import { createValidationErrorPD } from '@/utils/problem-document.js';

export const zValidator = <
  T extends ZodSchema,
  Target extends keyof ValidationTargets,
>(
  target: Target,
  schema: T
) =>
  zv(target, schema, (result, _c) => {
    if (!result.success) {
      return _c.json(
        createValidationErrorPD(_c.req.path, result.error.issues),
        StatusCodes.BAD_REQUEST
      );
    }
  });

The validator is used throughout the application, such as in the features/stores/add-store.ts file:

import { Hono } from 'hono';
import { v7 } from 'uuid';
import { StatusCodes } from 'http-status-codes';
import { stores, storeSchema } from './store.js';
import { zValidator } from '@/utils/validation.js';

const schema = storeSchema.omit({ storeId: true });

export const addRoute = new Hono().post(
  '/',
  zValidator('json', schema),
  async c => {
    const data = c.req.valid('json');
    const store = { ...data, storeId: v7() };
    stores.push(store);
    return c.json(store, StatusCodes.CREATED);
  }
);

All the references were updated from @hono/zod-validator to @/utils/validation.js.

Error Handlers in Hono

Hono provides two types of error handlers. These are special handlers that are called directly in error conditions, not part of the middleware chain. The ErrorHandler intercepts all unhandled errors thrown during request processing. Create the middlewares/on-error.ts file with the following content:

import { createInternalServerErrorPD } from '@/utils/problem-document.js';
import type { ErrorHandler } from 'hono';
import { StatusCodes } from 'http-status-codes';

export const onError: ErrorHandler = (_err, c) => {
  return c.json(
    createInternalServerErrorPD(c.req.path),
    StatusCodes.INTERNAL_SERVER_ERROR
  );
};

The NotFoundHandler is in charge of handling requests to undefined routes. Create the middlewares/on-not-found.ts file with the following content:

import type { NotFoundHandler } from 'hono';
import { StatusCodes } from 'http-status-codes';
import { createResourceNotFoundPD } from '@/utils/problem-document.js';

export const onNotFound: NotFoundHandler = c => {
  return c.json(
    createResourceNotFoundPD(c.req.path, 'Resource not found'),
    StatusCodes.NOT_FOUND
  );
};

Both handlers are registered in the app.ts file.

app.notFound(onNotFound);
app.onError(onError);

Security Middlewares

Hono provides several built-in security middlewares to protect our application from common web vulnerabilities:

• Basic Auth: Implements HTTP Basic Authentication.

• Bearer Auth: Validates Bearer tokens.

• JWT Auth: Verifies JWT tokens.

• JWK Auth: Authenticates using JSON Web Keys with dynamic key fetching.

• CORS: Controls cross-origin requests with configurable policies.

• CSRF Protection: Protects against Cross-Site Request Forgery attacks.

• Secure Headers: Sets comprehensive security headers including CSP, HSTS, and XSS protection.

• IP Restriction: limits access to resources based on the IP address of the user.

Apart from them, there are other third-party middleware we can check here. The project will implement token-based authentication and security-related HTTP headers. Update the app.ts file as follows:

import { Hono } from 'hono';
import { storeRoute } from './features/stores/index.js';
import { productRoute } from './features/products/index.js';
import { onError } from '@/middlewares/on-error.js';
import { onNotFound } from './middlewares/on-not-found.js';
import { bearerAuth } from 'hono/bearer-auth';
import { ENV } from './env.js';
import { secureHeaders } from 'hono/secure-headers';

export const app = new Hono({ strict: false });

app.use(secureHeaders());
if (ENV.TOKEN) {
  app.use('/api/*', bearerAuth({ token: ENV.TOKEN }));
}

app.route('/api', storeRoute);
app.route('/api', productRoute);

app.get('/live', c =>
  c.json({
    status: 'healthy',
    uptime: process.uptime(),
    timestamp: Date.now(),
  })
);

app.notFound(onNotFound);
app.onError(onError);

export type App = typeof app;

• Conditional protection: Authentication is only applied if a token is configured in the environment.

• Path-based protection: Only /api/* routes require authentication. The /live health check endpoint remains public.

• Wildcard patterns: Use path patterns like /api/* to protect entire route groups.

• Headers automatically added (among others):

  • X-Frame-Options: Prevents clickjacking attacks by controlling iframe embedding.

  • X-Content-Type-Options: Prevents MIME-sniffing attacks.

  • Referrer-Policy: Controls referrer information leakage.

  • Strict-Transport-Security: Enforces HTTPS connections (HSTS).

  • X-XSS-Protection: Enables browser XSS filters (legacy support).

Process-Level Error Handling

Node.js provides two critical process-level error events that must be handled to prevent silent failures and undefined application states.

Uncaught Exceptions

Uncaught exceptions are errors that happen during synchronous code execution and are not caught by any error-handling mechanism.

Unhandled Rejections

Unhandled rejections happen when a promise is rejected (asynchronous code), but there is no .catch() handler or try-catch block to manage the rejection.

Update the index.ts file as follows:

import { serve } from '@hono/node-server';
import { ENV } from '@/env.js';
import { app } from './app.js';

process.on('uncaughtException', err => {
  console.error(err.name, err.message);
  process.exit(1);
});

const server = serve(
  {
    fetch: app.fetch,
    port: ENV.PORT,
  },
  info => {
    console.log(
      `Server(${ENV.NODE_ENV}) is running on http://localhost:${info.port}`
    );
  }
);

process.on('unhandledRejection', (err: Error) => {
  console.error(err.name, err.message);
  server.close(() => {
    process.exit(1);
  });
});

Building secure, resilient APIs is an ongoing process. Stay informed about emerging threats, keep dependencies updated, and continuously refine error handling and security strategies. The patterns and practices covered in this article provide only a foundation for Hono applications. You can find all the code here. Thanks, and happy coding.

Hono Middlewares

Before diving into validation, it's essential to understand how Hono's middleware system works, as validators are implemented as middleware. Middleware functions are handlers that execute during the request-response cycle.

What is Hono Middleware?

A middleware is a function that accepts two parameters:

• Context (c) - Provides access to request data, environment bindings, and response utilities.

• Next (next) - An async function that executes the next middleware in the chain.

The middleware handler interface is defined as:

type MiddlewareHandler = (c: Context, next: Next) => Promise<Response | void>

How does Middleware Work?

The execution flow is:

• Each middleware is called in order.

• When await next() is called, the next middleware is executed.

• After the next() resolves, middleware can perform post-processing.

• The chain continues until a response is generated.

Each middleware can:

• Process the incoming request.

• Pass control to the next middleware using await next().

• Short-circuit the chain by returning a response.

• Modify the context object shared across all handlers.

What is Middleware For?

Middleware enables separation of concerns by handling cross-cutting functionality like:

• Authentication

  • Basic Auth: Validates username/password credentials.

  • Bearer Auth: Validates bearer tokens.

  • JWT: Verifies JSON Web Tokens and stores payload in context.

• HTTP Utilities

  • CORS: Handles Cross-Origin Resource Sharing headers.

  • ETag: Generates ETags and returns 304 responses for unchanged content.

  • Cache: Implements HTTP caching using the Cache API.

• Security

  • CSRF: Protects against Cross-Site Request Forgery attacks.

• Request Processing

  • Validation: Validates request data (JSON, form, query, params).

How to Use Middlewares?

A middleware can be applied globally to all routes, to specific path patterns, directly to individual routes, chained together, or through sub-app routing. Each method provides different levels of scope and control over request processing.

Global Application

Apply middleware to all routes using the wildcard pattern:

app.use('*', async (c, next) => {  
  console.log(`${c.req.method} : ${c.req.url}`)  
  await next()  
})

Path-Specific Application

Apply middleware to routes matching a path pattern:

// Apply to all routes under /api  
app.use('/api/*', cors())  
// Apply to specific route  
app.use('/hello', async (c, next) => {  
  await next()  
  c.res.headers.append('x-message', 'custom-header')  
})

Route-Level Application

Pass middleware directly as arguments to route methods:

// Single middleware with handler  
app.get('/protected', authMiddleware, (c) => {  
  return c.text('Authorized')  
})  
// Multiple middleware chained  
app.get('/api/data',   
  middleware1,  
  middleware2,  
  (c) => c.json({ data: 'success' })  
)

Chained Application

Chain multiple middleware calls for the same path:

app  
  .use('/chained/*', async (c, next) => {  
    c.req.raw.headers.append('x-before', 'abc')  
    await next()  
  })  
  .use(async (c, next) => {  
    await next()  
    c.header('x-after', c.req.header('x-before'))  
  })  
  .get('/chained/abc', (c) => {  
    return c.text('GET chained')  
  })

Sub-Application Routing

Apply middleware through sub-apps using app.route():

const api = new Hono()  
api.use('*', async (c, next) => {  
  await next()  
  c.res.headers.append('x-custom-a', 'a')  
})  

const middleware = new Hono()  
middleware.use('*', async (c, next) => {  
  await next()  
  c.res.headers.append('x-custom-b', 'b')  
})  

app.route('/api', middleware)  
app.route('/api', api)

Hono Validation System

Hono's validation system is built on middleware that intercepts requests, validates specific parts (body, query parameters, headers, path parameters), and either allows the request to proceed or returns validation errors.

hono/validator

hono/validator is a middleware that validates incoming request data across different targets (JSON body, form data, query parameters, path parameters, headers, and cookies) with full TypeScript type safety.

The validator function creates middleware that:

• Extracts data from a specific request target. The supported targets are:

  • Body Validation (json): Validates JSON request bodies.

  • Query Parameters (query): Validates URL query strings.

  • Path Parameters (param): Validates route parameters.

  • Headers (header): Validates HTTP headers.

  • Form Parameters (form): Validates form data from the request body.

  • Cookies (cookie): Validates HTTP cookies.

• Runs a validation function on the extracted data.

• Either returns an error response (short-circuiting) or stores validated data.

• Makes validated data accessible via c.req.valid(target).

app.get('/search',     
  validator('query', (value, c) => {    
    if (!value.q) {    
      return c.text('Parameter not found', 400)    
    }    
    return value as { q: string }    
  }),    
  (c) => {    
    const { q } = c.req.valid('query')
    return c.text(`Searching ${q}!!!`, 200)    
  }    
)

The validator function receives:

• value: The extracted data from the target.

• c: The Context object.

It can return:

• Validated data: Stored and accessible via c.req.valid().

• A Response object: Short-circuits the middleware chain with an error response.

• Throw an error: Propagates through the error handler.

Based on this validation system, the ecosystem provides adapters for multiple validation libraries:

• @hono/zod-validator: Uses Zod, supports v3/v4.

• @hono/valibot-validator: Uses Valibot, a modular validation approach.

• @hono/typebox-validator: Uses TypeBox, JSON Schema compliance.

• @hono/standard-validator: Uses Standard Schema V1 specification.

Implementing Zod Validations

Let's start by installing the following package:

npm install @hono/zod-validator

The validation starts with defining schemas. In the features/stores/store.ts file, we define the store data structure:

import { z } from 'zod';

export const storeSchema = z.object({
  storeId: z.uuidv7(),
  name: z.string().min(1).max(1024),
  url: z.url().min(1).max(2048),
});

export type Store = z.infer<typeof storeSchema>;

export const stores: Store[] = [];

This schema enforces several validation rules:

• storeId must be a valid UUIDv7.

• name must be a non-empty string with a maximum length of 1024 characters.

• url must be a valid URL with a maximum length of 2048 characters.

The Store type is automatically inferred from the schema, ensuring TypeScript types and runtime validation stay synchronized. The pagination schema in the types/pagination.ts file demonstrates Zod's advanced features:

import { z } from 'zod';

const DEFAULT_PAGE_NUMBER = 1;
const DEFAULT_PAGE_SIZE = 10;
const MAX_PAGE_SIZE = 100;

export const paginationSchema = z.object({
  pageNumber: z.coerce.number().min(1).optional().default(DEFAULT_PAGE_NUMBER),
  pageSize: z.coerce
    .number()
    .min(1)
    .max(MAX_PAGE_SIZE)
    .optional()
    .default(DEFAULT_PAGE_SIZE),
});

export const createPage = <TResult>(
  items: TResult[],
  totalCount: number,
  pageNumber: number,
  pageSize: number
) => {
  const totalPages = Math.ceil(totalCount / pageSize);
  return {
    items,
    pageNumber,
    pageSize,
    totalPages,
    totalCount,
  };
};

The z.coerce.number() method automatically converts string query parameters to numbers, which is essential since HTTP query parameters are always strings. The features/stores/add-store.ts file demonstrates body validation:

import { Hono } from 'hono';
import { v7 } from 'uuid';
import { StatusCodes } from 'http-status-codes';
import { stores, storeSchema } from './store.js';
import { zValidator } from '@hono/zod-validator';

const schema = storeSchema.omit({ storeId: true });

export const addRoute = new Hono().post(
  '/',
  zValidator('json', schema),
  async c => {
    const { name, url } = c.req.valid('json');
    const store = { name, url, storeId: v7() };
    stores.push(store);
    return c.json(store, StatusCodes.CREATED);
  }
);

• Uses storeSchema.omit({ storeId: true }) to generate a new schema excluding the storeId property since it's generated server-side.

• Validates the JSON request body with the zValidator('json', schema) middleware.

• Provides type-safe access to name and url from the validated body.

For retrieving a specific store in the features/stores/get-store.ts file, we validate the path parameter:

import { Hono } from 'hono';
import { stores, storeSchema } from './store.js';
import { StatusCodes } from 'http-status-codes';
import { zValidator } from '@hono/zod-validator';

const schema = storeSchema.pick({ storeId: true });

export const getRoute = new Hono().get(
  '/:storeId',
  zValidator('param', schema),
  async c => {
    const { storeId } = c.req.valid('param');
    const store = stores.find(s => s.storeId === storeId);
    if (!store) {
      return c.json(
        { message: `Store ${storeId} not found` },
        StatusCodes.NOT_FOUND
      );
    }
    return c.json(store, StatusCodes.OK);
  }
);

• storeSchema.pick({ storeId: true }) creates a new schema with only the storeId field.

• This ensures the URL parameter is a valid UUIDv7.

• The validated storeId is type-safe and guaranteed to match the schema.

In the features/stores/list-stores.ts file, we validate query parameters for listing stores:

import { Hono } from 'hono';
import { stores } from './store.js';
import { StatusCodes } from 'http-status-codes';
import { paginationSchema, createPage } from '@/types/pagination.js';
import { z } from 'zod';
import { zValidator } from '@hono/zod-validator';

const schema = paginationSchema.extend({
  name: z.string().optional(),
});

export const listRoute = new Hono().get(
  '/',
  zValidator('query', schema),
  async c => {
    const { pageNumber, pageSize, name } = c.req.valid('query');
    const pn = pageNumber;
    const pz = pageSize;
    let filteredStores = stores;

    if (name) {
      filteredStores = stores.filter(store =>
        store.name.toLowerCase().includes(name.toLowerCase())
      );
    }
    const totalCount = filteredStores.length;
    const startIndex = (pn - 1) * pz;
    const endIndex = startIndex + pz;
    const page = filteredStores.slice(startIndex, endIndex);
    return c.json(createPage(page, totalCount, pn, pz), StatusCodes.OK);
  }
);

• We extend the paginationSchema with an optional name filter.

• The zValidator('query', schema) middleware validates query parameters before the handler executes.

• c.req.valid('query') provides type-safe access to validated query parameters.

• If validation fails, a 400 error is returned automatically.

The edit store endpoint in the features/stores/edit-store.ts file shows how to validate request parts:

import { Hono } from 'hono';
import { StatusCodes } from 'http-status-codes';
import { stores, storeSchema } from './store.js';
import { zValidator } from '@hono/zod-validator';

const paramSchema = storeSchema.pick({ storeId: true });
const bodySchema = storeSchema.pick({ name: true, url: true });

export const editRoute = new Hono().put(
  '/:storeId',
  zValidator('param', paramSchema),
  zValidator('json', bodySchema),
  async c => {
    const { storeId } = c.req.valid('param');
    const { name, url } = c.req.valid('json');
    const store = stores.find(s => s.storeId === storeId);
    if (!store) {
      return c.json(
        { message: `Store ${storeId} not found` },
        StatusCodes.NOT_FOUND
      );
    }
    store.name = name;
    store.url = url;
    return c.json(store, StatusCodes.OK);
  }
);

Multiple validators can be chained, each validating a different part of the request. The order matters: validators execute in the order they're declared.

The combination of Hono's middleware system and Zod's type-safe validation provides a powerful foundation for building robust APIs with minimal boilerplate. By mastering validation patterns, we'll build APIs that are more secure, maintainable, and easier to work with for both our team and API consumers. You can find all the code here. Thanks, and happy coding.

The Hono Application Object

The Hono class serves as the foundation of every Hono application. It encapsulates the application's routing table, middleware stack, and request handling logic.

import { Hono } from 'hono'  
const app = new Hono()

The Hono constructor accepts a single optional parameter, including the following properties:

• strict: Controls strict mode for path matching (distinguishes /path from /path/). The default value is true.

• router: Specifies which router to use. The default router is SmartRouter.

• getPath: Custom function to extract path from request.

The Hono class also has three generic type parameters:

• E: Defines the shape of environment-specific types for our application. Uses BlankEnv by default. The environment type extends from the Env type and defines two properties:

  • Bindings: Access platform-specific resources, with full type safety, via the c.env variable.

  • Variables: Share typed data between middleware and handlers via c.set() and c.get().

type MyEnv = {  
  Variables: {  
    foo: string  
  }  
  Bindings: {  
    flag: boolean  
  }  
}  
const app = new Hono<MyEnv>()  

app.get('/', (c) => {  
  const foo = c.get('foo') 
  const flag = c.env.flag  
  ...
})

• S: Enables automatic type inference for API validation and type-safe client generation. Uses BlankSchema by default. The schema type extends from the Schema type. When we add routes, Hono's type system automatically constructs the schema using the ToSchema type. Therefore, defining a schema type is not common.

• BasePath: Enforces type safety for base path routing. Uses / by default.

These generics parameters enable Hono's compile-time type-safety and automatic client generation.

Hono Routing System

Hono's routing system matches incoming HTTP requests to registered handlers based on the request method and URL path. The router supports static paths, dynamic parameters, and wildcard patterns.

Route Registration

In Hono, we can register routes using several methods that are implemented in the Hono class:

HTTP Method Handlers

The most common way is using HTTP method handlers (get, post, put, delete, options, patch, all).

app.get('/api', (c) => c.text('Hello'))

Custom Methods with on()

Register handlers for custom or multiple HTTP methods.

app.on(['GET', 'POST'], '/api', (c) => c.text('Hello'))

Middleware with use()

Register middleware that runs before route handlers.

app.use('/api', middleware)

Mounting Sub-applications with route()

Mount another Hono instance under a specific path.

const userApp = new Hono()  
userApp.get('/users', (c) => c.text('Hello'))
// Mount under /api/v1  
app.route('/api/v1', userApp)

Base Path with basePath()

Create a new Hono instance with a base path prefix.

const api = new Hono().basePath('/api')  
api.get('/users', (c) => c.text('Hello'))
// Results in: /api/users

Route Matching

Routes are matched using the router's match() method. Hono supports:

• Static routes: /users

• Parameter routes: /users/:id

• Wildcard routes: /api/*

• Optional parameters: /posts/:id?

• Custom regex patterns: /files/:name{.*}

Route Matching Priority

Hono evaluates routes in the order they are defined. More specific routes should be registered before generic ones.

Request Processing

When a request hits our application:

1. Path Extraction: Hono extracts the path from the request URL.

2. Route Matching: The router finds matching handlers based on method and path.

3. Context Creation: A Context object is created with request data.

4. Handler Execution: Our code runs with access to the Context object.

The Context Object

The Context class is the central hub for handling individual requests, providing access to request data, response helpers, and variable storage.

Properties

• req: Provides access to the HonoRequest object containing request data.

• env: Provide access to the environment bindings properties.

• error: Error object if the handler threw an error.

• res: Provides access to the Response object.

Methods

• The Context class provides type-safe response helpers:

app.get('/text', (c) => c.text('Hello', 200))  
app.get('/json', (c) => c.json({ message: 'Hello' }, 201))  
app.get('/html', (c) => c.html('<h1>Hello</h1>'))  
app.get('/redirect', (c) => c.redirect('/target'))

• status: Sets the response HTTP status code.

• header: Sets HTTP headers for the response.

Variable Storage

The Context class provides type-safe variable storage through set() and get() methods:

app.use('*', async (c, next) => {  
  c.set('startTime', Date.now())  
  await next()  
  const duration = Date.now() - c.get('startTime')  
  c.header('X-Duration', duration.toString())  
})

We can also access the value of a variable with c.var.

The HonoRequest Object

The HonoRequest class wraps the raw Request object, providing convenient accessors for request data.

• path: The pathname of the request (without query string).

• method: HTTP method of the request.

• url: The full request URL.

• raw: The raw Request object.

Parameter Access

// Single parameter  
const id = c.req.param('id')  
// All parameters as object  
const { id, name } = c.req.param()

Query String Handling

// Single query value  
const page = c.req.query('page')  
// All queries as object  
const { page, limit } = c.req.query()    
// Multiple values for same key  
const tags = c.req.queries('tags') // string[]

Body Parsing

// JSON body  
const data = await c.req.json<T>()  
// Text body  
const text = await c.req.text()  
// Form data (multipart or urlencoded)  
const formData = await c.req.parseBody()  
// Raw body methods  
const arrayBuffer = await c.req.arrayBuffer()  
const blob = await c.req.blob()  
const formData = await c.req.formData()

Headers

// Single header  
const userAgent = c.req.header('User-Agent')  
// All headers as object  
const headers = c.req.header()

Building an Application

We'll implement a complete API for tracking price changes. This demonstrates practical routing patterns and context usage. This application will evolve as we write new articles about Hono. The starting point will be the project setup we built in the post Hono: Setting up the development environment. Let’s start by instaling the following packages:

npm install uuid
npm install http-status-codes

Create the file features/stores/store.ts file with the following content:

export type Store = {
  storeId: string;
  name: string;
  url: string;
};

export const stores: Store[] = [];

• Store defines the TypeScript type for store objects.

• stores is a module-level array serving as in-memory storage.

Create the file features/stores/add-stores.ts file with the following content:

import { Hono } from 'hono';
import { v7 } from 'uuid';
import { StatusCodes } from 'http-status-codes';
import { stores } from './store.js';

export const addRoute = new Hono().post('/', async c => {
  const { name, url } = await c.req.json();
  const store = { name, url, storeId: v7() };
  stores.push(store);
  return c.json(store, StatusCodes.CREATED);
});

The addRoute handler in add-store.ts accepts JSON payloads and creates new stores.

• c.req.json() parses the request body as JSON.

• v7() from the uuid package generates a UUID v7 identifier.

• stores.push(store) adds the new store to the in-memory stores array.

• c.json(store, StatusCodes.CREATED) returns the created store with a 201 status code.

Create the file features/stores/get-store.ts file with the following content:

import { Hono } from 'hono';
import { stores } from './store.js';
import { StatusCodes } from 'http-status-codes';

export const getRoute = new Hono().get('/:storeId', async c => {
  const storeId = c.req.param('storeId');
  const store = stores.find(s => s.storeId === storeId);
  if (!store) {
    return c.json(
      { message: `Store ${storeId} not found` },
      StatusCodes.NOT_FOUND
    );
  }
  return c.json(store, StatusCodes.OK);
});

The getRoute handler in get-store.ts fetches stores by ID.

• Returns StatusCodes.NOT_FOUND (404) when the store doesn't exist.

Create the file features/stores/list-stores.ts file with the following content:

import { Hono } from 'hono';
import { stores } from './store.js';
import { StatusCodes } from 'http-status-codes';

export const listRoute = new Hono().get('/', async c => {
  const { pageNumber, pageSize, name } = c.req.query();
  const pn = parseInt(pageNumber || '1', 10);
  const pz = parseInt(pageSize || '10', 10);
  let filteredStores = stores;
  if (name) {
    filteredStores = stores.filter(store =>
      store.name.toLowerCase().includes(name.toLowerCase())
    );
  }
  const totalCount = filteredStores.length;
  const startIndex = (pn - 1) * pz;
  const endIndex = startIndex + pz;
  const page = filteredStores.slice(startIndex, endIndex);
  return c.json(
    {
      items: page,
      pageNumber: pn,
      pageSize: pz,
      totalPages: Math.ceil(totalCount / pz),
      totalCount,
    },
    StatusCodes.OK
  );
});

The listRoute handler in list-stores.ts supports pagination and filtering.

• c.req.query() retrieves all query parameters as an object.

• The handler implements pagination with pageNumber and pageSize parameters.

• Case-insensitive filtering is applied when the name parameter is provided.

• Returns pagination metadata for client consumption.

Create the file features/stores/edit-store.ts file with the following content:

import { Hono } from 'hono';
import { stores } from './store.js';
import { StatusCodes } from 'http-status-codes';

export const editRoute = new Hono().put('/:storeId', async c => {
  const storeId = c.req.param('storeId');
  const { name, url } = await c.req.json();
  const store = stores.find(s => s.storeId === storeId);
  if (!store) {
    return c.json(
      { message: `Store ${storeId} not found` },
      StatusCodes.NOT_FOUND
    );
  }
  store.name = name;
  store.url = url;
  return c.json(store, StatusCodes.OK);
});

• Combines route parameters (storeId) and request body (name, url).

• Mutates the existing store object directly in the stores array.

• Returns 404 if the store doesn't exist.

As we mentioned, Hono supports composing applications from smaller, feature-focused sub-applications. Create the file features/stores/index.ts file with the following content:

import { Hono } from 'hono';
import { listRoute } from './list-stores.js';
import { addRoute } from './add-store.js';
import { getRoute } from './get-store.js';
import { editRoute } from './edit-store.js';

export const storeRoute = new Hono()
  .basePath('/stores')
  .route('/', listRoute)
  .route('/', addRoute)
  .route('/', getRoute)
  .route('/', editRoute);

• Each feature (list, add, get, edit) has its own Hono instance.

• route('/', subRoute) mounts multiple sub-routes at the same base path.

• Hono automatically merges routes based on HTTP methods and path patterns.

Create the app.ts file with the following content:

import { Hono } from 'hono';
import { storeRoute } from './features/stores/index.js';

export const app = new Hono({ strict: false });

app.route('/api', storeRoute);

app.get('/live', c =>
  c.json({
    status: 'healthy',
    uptime: process.uptime(),
    timestamp: Date.now(),
  })
);

export type App = typeof app;

• new Hono({ strict: false }) creates a Hono instance with non-strict routing, allowing trailing slashes in URLs to be ignored.

• app.route() mounts sub-applications at specific base paths, enabling modular route organization.

• app.get() registers a simple health check endpoint.

Update the index.ts file with the following content:

import { serve } from '@hono/node-server';
import { ENV } from '@/env.js';
import { app } from './app.js';

serve(
  {
    fetch: app.fetch,
    port: ENV.PORT,
  },
  info => {
    console.log(
      `Server(${ENV.NODE_ENV}) is running on http://localhost:${info.port}`
    );
  }
);

• @hono/node-server provides the Node.js adapter for Hono.

• app.fetch is Hono's standard request handler compatible with the Fetch API.

The API demonstrated in this article showcases Hono's core routing capabilities, including:

• Route definition and parameter extraction

• Request body parsing and response formatting

• Modular route organization with sub-applications

You can find all the code here. Thanks, and happy coding.

This article explores Axios interceptors in depth, from basic concepts to advanced implementations using popular interceptor libraries. By the end, we'll understand how to leverage interceptors to add logging, automatic retries, authentication, and caching to our HTTP layer.

Express API Server

First, let's create a realistic API server that simulates various scenarios to test our interceptors. Run the command npm init and create the server.js file with the following content:

app.get('/api/success', (req, res) => {
  res.json({ 
    message: 'OK',
    timestamp: new Date().toISOString()
  });
});

app.get('/api/fail', (req, res) => {
  res.status(500).json({ error: 'NO OK' });
});

app.get('/api/delay', async (req, res) => {
  const seconds = parseInt(req.query.seconds) || 1;
  const delay = seconds * 1000;

  await new Promise(resolve => setTimeout(resolve, delay));

  res.json({ 
    message: 'OK'
  });
});

app.get('/api/random-fail', (req, res) => {
  const failureRate = parseInt(req.query.percentage) || 50;
  const randomValue = Math.random() * 100;
  if (randomValue < failureRate) {
    res.status(500).json({ 
      error: 'NO OK',
    });
  } else {
    res.json({ 
      message: 'OK',
      timestamp: new Date().toISOString()
    });
  }
});

app.get('/api/protected', (req, res) => {
  const header = req.headers.authorization;

  if (!header) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const token = header.replace('Bearer ', '');

  if (token !== 'ABC') {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  res.json({ 
    message: 'OK',
    timestamp: new Date().toISOString()
  });
});

We can start the server at any time by running the command node server.js.

What is Axios?

Axios is a promise-based HTTP client for the browser and Node.js. It provides a simple and intuitive API for making HTTP requests with built-in support for features that would require additional code with native solutions. Axios provides features like:

• Promise-based API: Clean async/await syntax support

• Automatic JSON transformation: Requests and responses are automatically converted

• Request/Response interceptors: Modify requests or responses globally

• Request cancellation: Built-in support for aborting requests

• Timeout configuration: Set time limits for requests

• And more…

Install Axios by running the command:

npm install axios

Here's a simple example that demonstrates the basics of Axios:

import axios from 'axios';

const client = axios.create({
  baseURL: 'http://localhost:3000'
});

async function run() {
    const response = await client.get('/api/success');
    console.log(response.data);
}

run();

Axios offers several configuration options, which we can find here. The most commonly used Axios parameters include:

• url: The server URL (required for all requests).

• method: HTTP method (defaults to get).

• baseURL: Base URL for relative URLs (commonly set for API clients).

• data: Request body data for POST, PUT, and PATCH.

• params: URL query parameters.

• headers: Custom headers (frequently used for auth, content-type).

• auth: HTTP Basic authentication.

• timeout: Request timeout in milliseconds.

• responseType: Expected response format (json, text, etc.).

• validateStatus: Custom status code validation.

Axios vs Fetch API

Understanding the differences between Axios and the native Fetch API helps us make informed decisions about which tool to use.

Fetch API

The Fetch API is the native JavaScript solution for making HTTP requests, available in modern browsers and Node.js (v18+).

Pros:

• No dependencies: Built into the platform, no installation required.

• Smaller bundle size: No additional library weight.

• Modern standard: Part of the web platform standard.

• Stream support: Native support for readable streams.

Cons:

• No timeout support: Requires manual implementation with AbortController.

• Manual JSON parsing: Must call .json() on responses.

• No automatic error handling: Network errors only; HTTP errors (4xx, 5xx) don't reject.

• Verbose error checking: Must check the response.ok manually.

• No interceptors: Requires wrapper functions for global behavior.

• No upload progress: Cannot track upload progress easily.

Axios

Pros:

• Built-in timeout: Simple timeout configuration.

• Automatic JSON handling: Automatic request/response transformation.

• Better error handling: HTTP errors automatically reject promises.

• Interceptors: Powerful request/response modification.

• Request cancellation: Clean API for aborting requests.

• Progress tracking: Built-in upload/download progress events.

• Backward compatibility: Works in older browsers with polyfills.

Cons:

• External dependency: Adds ~13KB to our bundle (minified).

• Additional maintenance: Depends on third-party library updates.

• Learning curve: Additional API concepts to understand.

Common Use Cases

• Choose Axios when: We need interceptors, automatic error handling, timeout support, or are building a complex application with consistent HTTP patterns.

• Choose Fetch when: We want zero dependencies, need advanced streaming capabilities, or are building a simple application with minimal HTTP requirements.

Interceptors

Interceptors are functions that Axios calls for every request or response. They allow us to modify requests before they're sent or process responses before they reach our application code. Think of them as middleware for our HTTP client.

Types of Interceptors

Request Interceptors: Execute before a request is sent to the server. Common uses include:

• Adding authentication tokens

• Logging requests

• Modifying headers

• Transforming request data

Response Interceptors: Execute after a response is received but before it reaches our application. Common uses include:

• Handling errors globally

• Logging responses

• Caching responses

Here's a basic example demonstrating both request and response interceptors:

import axios from 'axios';

const client = axios.create({
  baseURL: 'http://localhost:3000'
});

client.interceptors.request.use(
  (config) => {
    console.log('Request:', config.method.toUpperCase(), config.url);
    config.metadata = { startTime: Date.now() };   
    return config;
  },
  (error) => {
    console.error('Request error:', error);
    return Promise.reject(error);
  }
);

client.interceptors.response.use(
  (response) => {
    const duration = Date.now() - response.config.metadata.startTime;
    console.log('Response:', response.status, `(${duration}ms)`);
    return response;
  },
  (error) => {
    if (error.response) {
      console.error('Response error:', error.response.status);
    } else if (error.request) {
      console.error('No response received');
    } else {
      console.error('Request setup error:', error.message);
    }
    return Promise.reject(error);
  }
);

run();

In this example, the request interceptor logs outgoing requests and adds metadata for timing. The response interceptor calculates request duration and handles errors consistently across the application.

Interceptor Execution Order

Understanding how interceptors execute is crucial for implementing complex behaviors. Axios processes interceptors in a specific order that resembles a middleware chain.

Request Interceptor Order

Request interceptors execute in reverse order of registration. The last registered interceptor runs first. This reverse order means that interceptors registered later have priority and can modify the configuration before earlier interceptors see it. This is useful when we want to override default behaviors.

Response Interceptor Order

Response interceptors are executed in the order of registration. The first registered interceptor runs first.

import axios from 'axios';

const client = axios.create({
  baseURL: 'http://localhost:3000'
});

client.interceptors.request.use((config)=>{
  console.info('logging interceptor');
  return config;
}, (error) => Promise.reject(error));

client.interceptors.request.use((config)=>{
  console.info('Request interceptor 2');
  return config;
}, (error) => Promise.reject(error));

client.interceptors.request.use((config)=>{
  console.info('Request interceptor 3');
  return config;
}, (error) => Promise.reject(error));

client.interceptors.response.use((response)=>{
  console.info('Response interceptor 1');
  return response;
}, (error) => Promise.reject(error));

client.interceptors.response.use((response)=>{
  console.info('Response interceptor 2');
  return response;
}, (error) => Promise.reject(error));

client.interceptors.response.use((response)=>{
  console.info('Response interceptor 3');
  return response;
}, (error) => Promise.reject(error));


async function run() {
    const response = await client.get('/api/success');
    console.log(response.data);
}

run();

In the example above, the request/response cycle follows this pattern:

Request Interceptor 3 (last registered)
↓
Request Interceptor 2
↓
Request Interceptor 1 (first registered)
↓
HTTP Request sent to server
↓
HTTP Response received from server
↓
Response Interceptor 1 (first registered)
↓
Response Interceptor 2
↓
Response Interceptor 3 (last registered)
↓
Response returned to application

Understanding this order is essential when combining multiple interceptors:

1. Authentication should be added early in the request chain: Register auth interceptors(request) last so they run first.

2. Retry logic needs an early position in the response chain: Register retry interceptors(response) first, so they handle errors before other error handlers.

3. Caching should happen late in the response chain: Register cache interceptors(response) last so they receive fully processed responses.

4. Logging should generally ocurr at both ends: Register loggers first for requests (so they run last) and first for responses (so they run first) to capture the final state.

Popular Interceptor Libraries

Logging: axios-logger

The axios-logger library automatically logs information about every HTTP request and response. When we add it to our Axios instance, it intercepts both requests and responses to provide detailed debugging information. Use it only in development. Install it by running the command npm install axios-logger.

import axios from 'axios';
import * as AxiosLogger from 'axios-logger';

const client = axios.create({
  baseURL: 'http://localhost:3000'
});

client.interceptors.request.use(
  (request) => AxiosLogger.requestLogger(request, {
    prefixText: 'API',
  }),
  (error) => AxiosLogger.errorLogger(error, {
    prefixText: 'API',
    logger: console.error
  })
);  

client.interceptors.response.use(
  (response) => AxiosLogger.responseLogger(response, {
    prefixText: 'API',
  }),
  (error) => AxiosLogger.errorLogger(error, {
    prefixText: 'API',
    logger: console.error
  })
);

async function run() {
  await client.get('/api/success');
  try {
      await client.get('/api/fail');
  } catch (error) {
  }
}

run();

We can configure the following parameters in axios-logger to control what information is logged and how it's formatted:

• method: Include HTTP method. The default value is true.

• url: Include request URL. The default value is true.

• params: Include URL query parameters. The default value is false.

• data: Include request/response body data. The default value is true.

• status: Include HTTP status code. The default value is true.

• statusText: Include HTTP status text. The default value is true.

• headers: Include HTTP headers. The default value is false.

• prefixText: Custom prefix text or false to disable. The default value is Axios.

• dateFormat: Timestamp format or false to disable. The default value is false.

• logger: Custom logger function. The default value is console.log.

Security: axios-token-interceptor

The axios-token-interceptor library simplifies adding authentication tokens to requests. It handles token storage, cache handling, and automatic injection. Install it by running the command npm install axios-token-interceptor.

import axios from 'axios';
import tokenProvider from 'axios-token-interceptor';

const client = axios.create({
  baseURL: 'http://localhost:3000'
});

const cache = tokenProvider.tokenCache(  
  ()  => Promise.resolve("ABC"),  
  { maxAge: 3600000 } 
);  

client.interceptors.request.use(
  tokenProvider({
    getToken: cache
  })
);

async function run() {
  const response = await client.get('/api/protected');
  console.log(response.data);
}

run();

We can configure parameters for two main functions in the axios-token-interceptor library:

Token Provider Parameters

• token: Static token string for all requests.

• getToken: Function that returns a token (sync or async).

• header: HTTP header name for token injection. The default value is Authorization.

• headerFormatter: Function to format the header value. The default value is (token) => 'Bearer ${token}'.

Either token or getToken must be provided.

Token Cache Parameters

• maxAge: Fixed cache duration in milliseconds.

• getMaxAge: Function to compute cache duration from token.

Either maxAge or getMaxAge should be provided for effective caching.

Caching: axios-cache-interceptor

The axios-cache-interceptor library adds sophisticated HTTP caching to Axios, dramatically reducing redundant network requests and improving application performance. Install it by running the command npm install axios-cache-interceptor.

import axios from 'axios';
import { setupCache } from 'axios-cache-interceptor';

const client = axios.create({
  baseURL: 'http://localhost:3000'
});

const clientWithCache = setupCache(client, {
  ttl: 15 * 60 * 1000
});

async function run() {
    const response = await clientWithCache.get('/api/success');
    console.log(response.data);

    const response2 = await clientWithCache.get('/api/success');
    console.log(response2.data);
}

run();

The axios-cache-interceptor uses both a request interceptor and a response interceptor internally:

1. The request interceptor runs before requests are sent to the network and is responsible for:

   • Generating cache keys for requests.

   • Checking if valid cached responses exist.

   • Serving cached responses when available.

   • Handling concurrent requests for the same resource.

   • Forwarding requests to the network when the cache is missing or stale.

2. The response interceptor (defaultResponseInterceptor) runs after responses are received from the network and handles:

   • Determining if responses should be cached.

   • Interpreting HTTP cache headers for TTL calculation.

   • Storing valid responses in cache.

   • Resolving pending concurrent requests.

   • Handling errors with stale cache fallback.

We can configure both global options when setting up the cache interceptor and per-request options for individual HTTP requests. Remember, we can set all per-request options as global defaults in setupCache().

Resilience: axios-retry

The axios-retry package adds intelligent retry logic to our Axios instance, automatically retrying failed requests based on configurable conditions. Install it by running the command npm install axios-retry.

import axios from 'axios';
import axiosRetry from 'axios-retry';

const client = axios.create({
  baseURL: 'http://localhost:3000'
});

client.interceptors.request.use(function (config) {
    console.log('Request interceptor registered before');
    return config;
  }, function (error) {
    console.log('Request error interceptor registered before');
    return Promise.reject(error);
  });

client.interceptors.response.use(function (response) {
    console.log('Response interceptor registered before');
    return response;
  }, function (error) {
    console.log('Response error interceptor registered before');
    return Promise.reject(error);
  });


axiosRetry(client, {
  retries: 3,
  retryDelay: axiosRetry.exponentialDelay,
  retryCondition: (error) => {
    return axiosRetry.isNetworkOrIdempotentRequestError(error);
  },
  onRetry: (retryCount, error, requestConfig) => {
    console.log(`Retry attempt #${retryCount}`);
    console.log(`Error: ${error.message}`);
  }
});

client.interceptors.request.use(function (config) {
    console.log('Request interceptor registered after');
    return config;
  }, function (error) {
    console.log('Request error interceptor registered after');
    return Promise.reject(error);
  });

client.interceptors.response.use(function (response) {
    console.log('Response interceptor registered after');
    return response;
  }, function (error) {
    console.log('Response error interceptor registered after');
    return Promise.reject(error);
  });


async function run() {
  try {
      const response = await client.get('/api/random-fail?percentage=90');
      console.log(response.data);
  } catch (error) {
      console.log(`Error: ${error.message}`);
  }
}

run();

The axios-retry function installs two interceptors into the Axios instance:

1. The request interceptor initializes the retry state and configures response validation.

2. The response interceptor handles error processing and retry logic execution.

When axios-retry performs a retry, the request passes through the entire Axios interceptor chain again. So, understanding the execution order is especially important when we combine it with other interceptors. In the example above, the output will look something like this (when all retries fail):

Request interceptor registered after
Request interceptor registered before
Response error interceptor registered before
Retry attempt #1
Error: Request failed with status code 500
Request interceptor registered after
Request interceptor registered before
Response error interceptor registered before
Retry attempt #2
Error: Request failed with status code 500
Request interceptor registered after
Request interceptor registered before
Response error interceptor registered before
Retry attempt #3
Error: Request failed with status code 500
Request interceptor registered after
Request interceptor registered before
Response error interceptor registered before
Response error interceptor registered after
Response error interceptor registered after
Response error interceptor registered after
Response error interceptor registered after
Error: Request failed with status code 500

Each retry follows this sequence:

Request interceptor registered after  
Request interceptor registered before    
Response error interceptor registered before  
Retry attempt #N  
Error: Request failed with status code 500

As we mentioned, request interceptors are executed in reverse registration order. Then, the response interceptors are executed in order. Notice that the last interceptor registered never appears during retry attempts; it only shows up after all retries fail. When a request fails, axios-retry's response interceptor catches the error and decides whether to retry.

• If retryable, it creates a new request, so the error never reaches subsequent interceptors.

• If not retryable, the error is rejected and continues through the interceptor chain.

After 3 failed retries, the error flows through all remaining response error interceptors:

Response error interceptor registered after (x4)  
Error: Request failed with status code 500

The "after" interceptor runs 4 times because:

• 1 time for the original request failure.

• 3 times for each retry failure (when errors are finally rejected).

We can configure the following parameters:

• retries: Number of retry attempts before failing. The default value is 3.

• retryCondition: Callback to determine if the request should be retried.

• shouldResetTimeout: Whether timeout resets between retries. The default value is false.

• retryDelay: Delay function between retries (in ms).

• onRetry: Callback executed before each retry attempt.

• onMaxRetryTimesExceeded: Callback when all retries are exhausted.

• validateResponse: Callback to determine if response should be resolved/rejected.

Additionally, axios-retry provides several built-in functions to help with parameter configuration, organized into the following categories:

Error Classification Functions (for retryCondition)

• isNetworkError: Detects network connectivity issues.

• isRetryableError: Checks for HTTP errors worth retrying (429, 5xx).

• isSafeRequestError: Combines the isRetryableError check with safe HTTP methods (GET, HEAD, OPTIONS).

• isIdempotentRequestError: Combines the isRetryableError check with idempotent methods (GET, HEAD, OPTIONS, PUT, DELETE).

• isNetworkOrIdempotentRequestError: isNetworkError or isIdempotentRequestError. Default value for the retryCondition parameter.

Delay Functions (for retryDelay)

• noDelay: No delay between retries. Default value for the retryDelay parameter.

• exponentialDelay: Exponential backoff with 20% randomization.

• linearDelay: Linear delay progression, accepts custom delay factor.

All delay functions automatically respect the Retry-After header when present.

Testing: axios-mock-adapter

When writing tests, we should not hit real APIs. The axios-mock-adapter package intercepts requests at the adapter level to return mock data. Install it by running the command npm install axios-mock-adapter --save-dev.

import axios from 'axios';
import AxiosMockAdapter from "axios-mock-adapter";

const client = axios.create({
  baseURL: 'http://localhost:3000'
});

const mock = new AxiosMockAdapter(client);

mock.onGet("/api/success").reply(200, {
  users: [{ id: 1, name: "John Smith" }],
});

async function run() {
    const response = await client.get('/api/success');
    console.log(response.data);
}

run();

The axios-mock-adapter package intercepts requests by replacing the Axios adapter, not by adding interceptors. This approach allows it to mock requests before they reach the network while preserving the normal interceptor flow. During the AxiosMockAdapter creation, we can configure:

• delayResponse: delay for all responses in milliseconds.

• onNoMatch: Behavior when no handler matches. Values are passthrough or throwException

For each HTTP method handler, we can configure the URL matching:

• String: Exact URL match.

• RegExp: Pattern matching.

• Undefined: Match any URL.

Besides that, we can also set up matching by parameters, headers, and even the request body data. Each handler supports these response methods:

• reply: Returns a static(status, data, and headers) or dynamic(a function that returns a tuple, status, data, and headers) response.

• replyOnce: One-time response

• withDelayInMs: Delay per request.

• passThrough: Forward the request to the real server.

• networkError: Simulate network error.

• timeout: Simulate timeout.

• abortRequest: Simulate aborted request.

Combining Multiple Interceptors

Real-world applications often need multiple interceptor functionalities working together. Understanding how to combine them effectively is crucial for building robust HTTP clients. The following example combines three interceptors to create a production-ready API client with logging, automatic retries, and token-based authentication.

import axios from 'axios';
import * as AxiosLogger from 'axios-logger';
import axiosRetry from 'axios-retry';
import tokenProvider from 'axios-token-interceptor';

const client = axios.create({
  baseURL: 'http://localhost:3000',
});

client.interceptors.response.use(
  response => {
    const duration = Date.now() - response.config.metadata.startTime;
    console.log(`Request duration: ${duration}ms`);
    return AxiosLogger.responseLogger(response);
  },
  error => {
    const retryState = error.config['axios-retry']; 
    const isLastAttempt = retryState?.retryCount === retryState?.retries;
    if (isLastAttempt) {
        if (error.config?.metadata?.startTime) {
          const duration = Date.now() - error.config.metadata.startTime;
          console.log(`Request duration (error): ${duration}ms`);
        }
      return AxiosLogger.errorLogger(error);
    }
    return Promise.reject(error);
  }
);

axiosRetry(client, {
  retries: 3,
  retryDelay: axiosRetry.exponentialDelay,
  retryCondition: (error) => {
    return axiosRetry.isNetworkOrIdempotentRequestError(error);
  },
  onRetry: (retryCount, error, requestConfig) => {
    console.log(`Retry attempt #${retryCount}`);
  }
});

client.interceptors.request.use(
  tokenProvider({
    getToken: () => { 
        return "ABC";
      }
  })
);

client.interceptors.request.use(
  config => {
    const retryState = config['axios-retry']; 
    if (!retryState) {
      config.metadata = { startTime: Date.now() };
      return AxiosLogger.requestLogger(config);
    }
    return config;
  }
);


async function run() {
  try {
      const response = await client.get('/api/random-fail?percentage=50');
      console.log(response.data);
  } catch (error) {
      console.log(`Error: ${error.message}`);
  }
}

run();

The client instance has the following pipeline for every request:

• Starts a timer and calls AxiosLogger.requestLogger (only once, not on retries).

• axios-token-interceptor injects the token.

• axios-retry initializes the retry state.

• Request is executed.

• axios-retry handles retry logic execution.

• On error, logs duration and error using AxiosLogger.responseLogger only for the final retry attempt.

• On success, logs duration and response using AxiosLogger.responseLogger.

Axios interceptors provide a powerful mechanism for implementing cross-cutting concerns in your HTTP layer. By understanding and properly utilizing interceptors, we can create robust, maintainable, and feature-rich API clients. Thanks, and happy coding. You can find all the code here.

In this article, we analyze a real-world problem from a cost-first perspective and walk through three alternative implementations step by step. The goal is to help software developers internalize a repeatable method for cost analysis and provide practical techniques to prevent unexpected cloud bills.

The Problem

We have a public Single-Page Application (SPA) that stores logs locally in IndexedDB. A Service Worker collects and sends logs every 5 minutes, with approximately:

• Request size: ~20 log entries per request.

• Request weight: ~40 KB per request.

• Scale: 2,000 instances running 12 hours daily.

This results in:

• Requests per instance per day: 12 hours × (60 / 5) = 144 requests.

• Total requests per day: 144 × 2000 = 288,000 requests.

• Total requests per month: 288,000 × 30 = 8,640,000 requests.

• Daily log volume: 288,000 × 40 KB = 11.52 GB.

Logs must ultimately reach Splunk, which is only accessible privately. We are evaluating three architectural destinations to receive logs from the SPA.

Option 1: AWS Lambda (256MB)

An AWS Lambda function receives the request, processes it, and forwards it to Splunk over the private network.

Advantages:

• Zero infrastructure management.

• Auto-scaling without configuration.

• Built-in monitoring and logging.

Disadvantages:

• API Gateway adds latency.

• Cold starts can affect P99 latency.

Cost Analysis

• AWS Lambda Invocations:

  • Cost: $0.20 per 1 million requests.

  • Total Invocation Cost: 8,640,000 requests * $0.20/1,000,000 requests = $1.73

• AWS Lambda Compute Time:

  • Average Duration: 150 ms per request.

  • Total Compute (seconds): 8,640,000 requests * 150 ms/request = 1,296,000,000 ms = 1,296,000 seconds.

  • Total Compute (GB-seconds): 1,296,000 seconds * (256/1024) GB = 324,000 GB-seconds.

  • Cost: $0.0000166667 per GB-second.

  • Total Compute Cost: 324,000 GB-seconds * $0.0000166667/GB-second = $5.40

• AWS API Gateway (HTTP API)

  • Cost: $1.00 per million requests.

  • Total Requests Cost: 8,640,000 requests × $1/1,000,000 requests = $8.64

• Total Cost: $1.73 + $5.40 + $8.64 = $15.77

Option 2: Kubernetes Pod (256Mi, 256m CPU)

A lightweight API deployed as a Pod in an existing Kubernetes cluster.

Advantages:

• Lower per-request cost when using an existing cluster.

Disadvantages:

• Requires cluster management expertise.

• More complex deployment pipeline.

Cost Analysis

EKS Control Plane and ALB costs will not be included.

• Pod resource allocation:

  • Node Type: c7i-flex.xlarge (4 vCPU, 8 GB RAM).

  • Cost(On-Demand): $0.17/hour = $122.4/month.

  • CPU Pod Utilization: 0.256 vCPU / 4 vCPU = 6.4%

  • Memory Pod Utilization: 256 MB / 8192 MB = 3.1%

  • Allocated Cost by CPU: $122.4 × 0.064 = $7.83

  • Allocated Cost by Memory: $122.4 × 0.031 = $3.79

  • Total Allocated Cost: max($7.83, $3.79) = $7.83

• Total Cost: $7.83