integrations/nextjs

[giscus[bot]]

integrations/nextjs

With Next.js App Router, you can run Elysia on Next.js routes. Elysia will work normally as expected because of WinterCG compliance.

https://elysiajs.com/integrations/nextjs.html

[blackfyre]

Well... this is fun...

󰣛 blackfyre  …/trusted-payments/trusted-payments   main ✘!?   v22.17.0   20:13  
 bun dev
$ next dev --turbopack
   ▲ Next.js 15.5.2 (Turbopack)
   - Local:        http://localhost:3000
   - Network:      http://192.168.0.190:3000

 ✓ Starting...
 ✓ Ready in 702ms
 ○ Compiling /api/[[...slugs]] ...
 ✓ Compiled /api/[[...slugs]] in 1489ms
 ⨯ Detected default export in '[project]/src/app/api/[[...slugs]]/route.ts'. Export a named export for each HTTP method instead.
 ⨯ No HTTP methods exported in '[project]/src/app/api/[[...slugs]]/route.ts'. Export a named export for each HTTP method.
 ⨯ Detected default export in '[project]/src/app/api/[[...slugs]]/route.ts'. Export a named export for each HTTP method instead.
 ⨯ No HTTP methods exported in '[project]/src/app/api/[[...slugs]]/route.ts'. Export a named export for each HTTP method.
 GET /api 405 in 2286ms

Followed the description here.

[WomB0ComB0]

Genuine skill issue, give more details on your issue.
/api/v1/[[...route]]/route.ts

import { Stringify } from "@/utils";
import { cors } from '@elysiajs/cors';
import { opentelemetry } from '@elysiajs/opentelemetry';
import { serverTiming } from '@elysiajs/server-timing';
import { swagger } from '@elysiajs/swagger';
import { logger } from "@/utils";
import { SocketAddress } from "bun";
import { Elysia } from "elysia";
import { ip } from 'elysia-ip';
import { DefaultContext, type Generator, rateLimit } from 'elysia-rate-limit';
import { elysiaHelmet } from 'elysiajs-helmet';
import { batchSpanProcessor, IS_VERCEL, otelResource, permission, version } from "./constants";
import { apiRoutes, utilityRoutes } from "./elysia";

/**
 * Generates a unique identifier for rate limiting based on the request's IP address.
 * @param {*} _r - The request object (unused).
 * @param {*} _s - The response object (unused).
 * @param {{ ip: SocketAddress }} param2 - The context containing the IP address.
 * @returns {string} The IP address or 'unknown' if not available.
 */
const ipGenerator: Generator<{ ip: SocketAddress }> = (_r, _s, { ip }) => ip?.address ?? 'unknown';

const app = new Elysia({ prefix: "/api/v1" })
  .onParse(({ request, contentType }) => {
    if (contentType === 'multipart/form-data') {
      return request.formData();
    }
  })
  .use(utilityRoutes)
  .use(apiRoutes)
  .use(
    swagger({
      path: '/swagger',
      documentation: {
        info: {
          title: '🦊 Product Decoder API Server',
          version: version || '1.0.0',
          description: `
						**Product Decoder API Server**

						This API provides:
						- 🔍 **Search & Vision**: Google Custom Search, YouTube search, and reverse image search
						- 📰 **News**: GNews integration for articles and headlines
						- 🚀 **Performance**: OpenTelemetry tracing, rate limiting, and caching
						- 🔒 **Security**: Helmet security headers and CORS protection
						- 📊 **Monitoring**: Health checks, status endpoints, and observability

						> **Contact:** [API Support](mailto:support@your-api.com)
          `,
          contact: {
            name: 'API Support',
            email: 'support@your-api.com',
          },
        },
        tags: [
          {
            name: 'Utility',
            description: 'Status, version, and health check endpoints',
          },
          {
            name: 'Info',
            description: 'API information endpoints',
          },
          {
            name: 'Vision',
            description: 'Google Vision API integration',
          },
          {
            name: 'News',
            description: 'GNews API integration',
          },
          {
            name: 'Search',
            description: 'Google Custom Search integration',
          },
          {
            name: 'YouTube',
            description: 'YouTube Data API integration',
          },
        ],
      },
    }),
  )
  .trace(
    /**
     * Configures tracing hooks for before/after/error handling.
     * Logs timing and errors for each request.
     * @param {object} param0 - The tracing context.
     */
    async ({ onBeforeHandle, onAfterHandle, onError }) => {
      onBeforeHandle(({ begin, onStop }) => {
        onStop(({ end }) => {
          logger.debug('BeforeHandle took', { duration: end - begin });
        });
      });
      onAfterHandle(({ begin, onStop }) => {
        onStop(({ end }) => {
          logger.debug('AfterHandle took', { duration: end - begin });
        });
      });
      onError(({ begin, onStop }) => {
        onStop(({ end, error }) => {
          logger.error('Error occurred after trace', error, { duration: end - begin });
        });
      });
    },
  )
  .use(
    elysiaHelmet({
      csp: {
        defaultSrc: [permission.SELF],
        scriptSrc: [permission.SELF, permission.UNSAFE_INLINE],
        styleSrc: [permission.SELF, permission.UNSAFE_INLINE],
        imgSrc: [permission.SELF, permission.DATA, permission.HTTPS],
        useNonce: true,
      },
      hsts: {
        maxAge: 31_536_000,
        includeSubDomains: true,
        preload: true,
      },
      frameOptions: 'DENY',
      referrerPolicy: 'strict-origin-when-cross-origin',
      permissionsPolicy: {
        camera: [permission.NONE],
        microphone: [permission.NONE],
      },
    }),
  )
  .use(ip())
  .use(
    // Only use OpenTelemetry in local development
    batchSpanProcessor
      ? opentelemetry({
          resource: otelResource,
          spanProcessors: [batchSpanProcessor],
        })
      : new Elysia(),
  )
  .use(
    serverTiming({
      trace: {
        request: true,
        parse: true,
        transform: true,
        beforeHandle: true,
        handle: true,
        afterHandle: true,
        error: true,
        mapResponse: true,
        total: true,
      },
    }),
  )
  // --- CORS configuration for cross-origin requests ---
  .use(
    cors({
      origin: process.env.FRONTEND_URL || 'http://localhost:3000', // Configurable frontend URL
      methods: ['GET', 'POST', 'OPTIONS'], // Specify allowed HTTP methods
      allowedHeaders: ['Content-Type', 'Authorization'], // Specify allowed headers
      credentials: true, // Allow credentials (e.g., cookies, authorization headers)
      maxAge: 86_400, // Cache the preflight response for 24 hours
    }),
  )
  .use(
    rateLimit({
      duration: 60_000,
      max: 100,
      headers: true,
      scoping: 'scoped',
      countFailedRequest: true,
      errorResponse: new Response(
        Stringify({
          error: 'Too many requests',
        }),
        { status: 429 },
      ),
      generator: ipGenerator,
      context: new DefaultContext(10_000),
    }),
  )
  .onError(
    /**
     * Global error handler for the API.
     * Logs the error and returns a JSON error response.
     * @param {object} param0 - The error context.
     * @param {string} param0.code - The error code.
     * @param {Error} param0.error - The error object.
     * @param {object} param0.set - The response setter.
     * @returns {string} The JSON error response.
     */
    ({ code, error, set }) => {
      logger.error('API error handler', error, { code });
      set.status = code === 'NOT_FOUND' ? 404 : 500;
      return Stringify({
        error: error instanceof Error ? Stringify({ error }) : Stringify({ error }),
        status: set.status,
      });
    },
  );

export const GET = app.handle;
export const POST = app.handle;
export const PUT = app.handle;
export const DELETE = app.handle;
export const PATCH = app.handle;

/**
 * Gracefully shuts down telemetry on Vercel using waitUntil if available.
 * For local development, flushes the batch span processor.
 */
const shutdown = async (): Promise<void> => {
  if (IS_VERCEL) {
    // On Vercel, we can't rely on process signals, so this is mainly for cleanup
    logger.info('Vercel function cleanup');
  } else {
    logger.info('Shutting down 🦊 Elysia');
    if (batchSpanProcessor) {
      await batchSpanProcessor.forceFlush();
    }
  }
};

// Don't set up process listeners on Vercel
if (!IS_VERCEL) {
  process.on('SIGINT', shutdown);
  process.on('SIGTERM', shutdown);
}

export type App = typeof app;

[WomB0ComB0]

Something like this works dandy, with no other configuration or meddling with the next.config.ts or middleware.ts

[blackfyre]

@WomB0ComB0 I appreciate the input, the tone? Not so much.
The documentation page was updated ~3 weeks ago, my observation was posted ~5 weeks ago, and according to the documentation at the time, it was clear that the Elysia side was a couple steps behind Next.
Also, please don't confuse skill issues with a lack of time to be dedicated to a section of a project.

[WomB0ComB0]

@blackfyre apologies, yeah definitely. I would recommend Google dorking this query site:github.com nextjs elysia

[fish895623]

for nextjs 16

seems there some changes. notice this.

import { Elysia, t } from 'elysia'
import { swagger } from '@elysiajs/swagger'

const app = new Elysia({ prefix: '/api' })
  .use(
    swagger({
      documentation: {
        info: {
          title: 'Next.js + Elysia API',
          version: '1.0.0',
          description: 'Type-safe API built with Elysia.js and Next.js',
        },
        tags: [
          { name: 'General', description: 'General endpoints' },
          { name: 'Users', description: 'User management endpoints' },
          { name: 'Posts', description: 'Post management endpoints' },
        ],
      },
    })
  )
  .get('/', () => 'Hello from Elysia!', {
    detail: {
      tags: ['General'],
      summary: 'Root endpoint',
      description: 'Returns a simple greeting message',
    },
  })
  .get(
    '/health',
    () => ({
      status: 'ok',
      timestamp: new Date().toISOString(),
    }),
    {
      detail: {
        tags: ['General'],
        summary: 'Health check',
        description: 'Returns the API health status and current timestamp',
      },
    }
  )
  .get(
    '/users/:id',
    ({ params: { id } }) => ({
      id,
      name: `User ${id}`,
    }),
    {
      detail: {
        tags: ['Users'],
        summary: 'Get user by ID',
        description: 'Retrieves a user by their unique identifier',
      },
      params: t.Object({
        id: t.String({ description: 'User ID' }),
      }),
    }
  )
  .post(
    '/users',
    ({ body }) => ({
      success: true,
      user: body,
    }),
    {
      detail: {
        tags: ['Users'],
        summary: 'Create a new user',
        description: 'Creates a new user with the provided information',
      },
      body: t.Object({
        name: t.String({ description: 'User full name' }),
        email: t.String({ description: 'User email address', format: 'email' }),
      }),
    }
  )
  .get(
    '/posts',
    ({ query }) => ({
      posts: [
        { id: 1, title: 'First Post' },
        { id: 2, title: 'Second Post' },
      ],
      page: query.page || 1,
    }),
    {
      detail: {
        tags: ['Posts'],
        summary: 'Get all posts',
        description: 'Retrieves a paginated list of posts',
      },
      query: t.Object({
        page: t.Optional(t.Number({ description: 'Page number for pagination' })),
      }),
    }
  )

// Export type for Eden Treaty
export type App = typeof app

// Export HTTP method handlers
export const GET = app.handle
export const POST = app.handle
export const PUT = app.handle
export const DELETE = app.handle
export const PATCH = app.handle

app/api
└── [[...slug]]
    └── route.ts

[programming-with-ia]

this is the best way to handle errors in nextjs:

see: elysia-next-error-handler

import { Elysia, NotFoundError } from "elysia";
import { APIError } from "@/lib/api-error";
import { notFound } from "next/navigation";

const app = new Elysia({ prefix: "/api" })
  .onError(({ error, set }) => {
    if (error instanceof APIError) {
      set.status = error.status;
      return {
        success: false,
        message: error.message,
        code: error.code,
      };
    } else if (error instanceof NotFoundError) {
      notFound();
    } else if (isNextJsInternalError(error)) {
      throw error;
    }

    // Log the actual error for debugging
    console.error("Internal Server Error:", error);

    set.status = 500;
    return {
      success: false,
      message: "Internal Server Error",
    };
  })

function isNextJsInternalError(error: unknown): boolean {
  if (typeof error !== "object" || error === null || !("digest" in error)) {
    return false;
  }

  const digest = (error as { digest?: string }).digest;

  // Checks for NEXT_REDIRECT, NEXT_NOT_FOUND, etc.
  return typeof digest === "string" && digest.startsWith("NEXT_");
}

// lib/api-error.ts
export class APIError extends Error {
  constructor(
    public message: string,
    public status: number = 500,
    public code?: string
  ) {
    super(message);
  }
}

[nahoc]

As of 13-12-2025, thank you for adding the isomorphic fetch pattern. This enables ISR on NextJS powered by Elysia. 🙏

[tonpascual]

Is type safety achievable on standalone Elysia backend server running on a port?

[blackfyre]

Is type safety achievable on standalone Elysia backend server running on a port?

Typescript does not equal runtime type safety, it only gives hints and enforces a couple things in your IDE of choice and during transpiling.
If you want runtime typesafety, I'd recommend you look at: go, rust, elixir, ...
As for the runtime environment, except for a couple situations (like with php) your application will run on a port of your choice.

[nahoc]

shouldn't it be instead export const api = typeof window !== "undefined" ? treaty<App>("localhost:3000").api : treaty(app).api;

[nahoc]

Using process won't work since it's defined in both server and client, or am I misunderstanding?

[Wiredista]

When using it with Next, it seems to instantiate Elysia in every API call, making the database connections being rebuilt in every call. Anyone knows how to make them persistent?

import Elysia from "elysia";
import { fromTypes, openapi } from "@elysiajs/openapi";

import * as routes from "@src/routes"; // These routes use database connections
import { Logger } from "@src/lib/logger"; // In logs I see that every API call logs that the connections are being connected again.

const app = new Elysia({
    prefix: "/api",
})
    .use(openapi())
    .use(routes.categories)
    .use(routes.comandas)
    .use(routes.items)
    .use(routes.restaurants)
    .use(routes.images)
    .use(routes.orders)
    .use(routes.serviceAccounts)
    .use(routes.sessions)
    .use(routes.users)
    .use(routes.analytics)

export const GET = app.fetch
export const POST = app.fetch
export const HEAD = app.fetch
export const PUT = app.fetch
export const DELETE = app.fetch
export const OPTIONS = app.fetch

[Wiredista]

Alright, it seems to be happening only when using bun run dev (aka next dev) command. It does not happen when serving after built, which is great. But it would be nice to have a fix for this if anyone has.

[XshubhamG]

treaty(app).api is giving error since the file only importing the type for app.

export const api =
  typeof process !== 'undefined'
    ? treaty(app).api
    : treaty<typeof app>('localhost:3000').api

[ALDRICHCODE45]

did you find any way to solve the issue?

[XshubhamG]

// .api to enter /api prefix
export const api = treaty<typeof app>('localhost:3000').api

[XshubhamG]

No, I couIdn't find any solution I just remove the type check temporarily

[ALDRICHCODE45]

I'm not getting linter errors in this code:

import { Elysia, t } from "elysia";

export const app = new Elysia({ prefix: "/api" })
.get(
"/",
() => {
return {
ok: true,
message: "Mensaje desde elysia",
};
},
{
response: {
200: t.Object({
ok: t.Boolean(),
message: t.String(),
}),
},
}
)
.post("/", ({ body }) => body, {
body: t.Object({
username: t.Boolean(),
password: t.String({ minLength: 2 }),
}),
});

export const GET = app.fetch;
export const POST = app.fetch;

// Exporta el tipo de la app para Eden Treaty - CRÍTICO para type safety
export type App = typeof app;
import { api } from "@/lib/eden";

export default async function Home() {
const { data } = await api.get();

const response = await api.post({
password: "aldrich_code34",
username: "aldrich",
});

console.log({ response });

return (
<>

{JSON.stringify(data)}

Response: {JSON.stringify(response.data)}

{response.error && (
<div style={{ color: "red" }}>
Error {response.error.status}:{" "}
{JSON.stringify(response.error.value.property)}
{JSON.stringify(response.error.value.message)}

)}
</>
);
}
this should give me a linter error am i right??

[nahoc]

I use the following without problems

import { type Treaty, treaty } from "@elysiajs/eden";
import { app } from "@/app/api/[[...apiRoutes]]/route";

// .api to enter /api prefix
export const api = typeof window !== "undefined" ? treaty<typeof app>(window.location.origin).api : treaty(app).api;

[ALDRICHCODE45]

what version of elysia are you using??

[nahoc]

actually you are right, this doesn't work if you use say import "server-only"

this is because we are importing app, even though we only use it as a type in the client version, it still gets included in the bundle.

I wonder what the fix is for this.

[ALDRICHCODE45]

thank you for your help!! if you find any way to solve this, please let me know!!

[shiqocred]

If I want to run Elysia on the Node.js runtime instead of Bun, do I need to use the Node adapter?

[programming-with-ia]

no