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?