{"id":31592600,"url":"https://github.com/treblle/treblle-nextjs","last_synced_at":"2026-07-14T17:40:39.059Z","repository":{"id":317474997,"uuid":"976249794","full_name":"Treblle/treblle-nextjs","owner":"Treblle","description":"Next.js SDK","archived":false,"fork":false,"pushed_at":"2026-03-17T16:32:53.000Z","size":311,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-18T05:44:36.454Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Treblle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-01T19:11:44.000Z","updated_at":"2026-03-17T16:33:31.000Z","dependencies_parsed_at":"2025-10-01T06:05:50.095Z","dependency_job_id":"abfc685b-a182-4931-b8c3-4abb570bc700","html_url":"https://github.com/Treblle/treblle-nextjs","commit_stats":null,"previous_names":["treblle/treblle-nextjs","treblle/treblle-js"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Treblle/treblle-nextjs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Ftreblle-nextjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Ftreblle-nextjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Ftreblle-nextjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Ftreblle-nextjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Treblle","download_url":"https://codeload.github.com/Treblle/treblle-nextjs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Treblle%2Ftreblle-nextjs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35472809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-14T02:00:06.603Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-06T03:11:30.686Z","updated_at":"2026-07-14T17:40:39.053Z","avatar_url":"https://github.com/Treblle.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Treblle - API Intelligence Platform\n\n[![Treblle API Intelligence](https://github.com/user-attachments/assets/b268ae9e-7c8a-4ade-95da-b4ac6fce6eea)](https://treblle.com)\n\n[Website](http://treblle.com/) • [Documentation](https://docs.treblle.com/) • [Pricing](https://treblle.com/pricing)\n\nTreblle is an API intelligence platfom that helps developers, teams and organizations understand their APIs from a single integration point.\n\n---\n\n## Treblle Next.js SDK\n\nTreblle Next.js SDK that supports Pages Router (`pages/api`) and App Router (`app/api`) supported\n\n## Requirements\n \n- Node.js: Follows your Next.js version requirements (Node 18+ recommended)\n- Runtimes: Node.js and Edge (see Edge notes)\n\n## Installation\n\n```bash\nnpm install @treblle/next\n# or\npnpm add @treblle/next\n# or\nyarn add @treblle/next\n```\n\nKeep keys server-only. Do not expose with `NEXT_PUBLIC_`.\n\n## Get Your Keys\n\n1. Create a free account: https://treblle.com\n2. Create a project to get:\n   - `sdkToken`\n   - `apiKey`\n3. Add to your `.env` (server-only):\n\n```env\nTREBLLE_SDK_TOKEN=your_sdk_token\nTREBLLE_API_KEY=your_api_key\n```\n\n## Quick Start\n\nPick your routing setup:\n\n- Pages Router: wrap `pages/api/*` handlers\n- App Router: wrap `app/api/*` route method exports\n- Middleware (optional): observe all requests at the edge (with body limits)\n\n### Pages Router (pages/api)\n\n`pages/api/users.ts`\n\n```ts\nimport type { NextApiRequest, NextApiResponse } from 'next';\nimport { withTrebllePages } from '@treblle/next/integrations/nextjs';\n\nconst treblle = withTrebllePages({\n  sdkToken: process.env.TREBLLE_SDK_TOKEN!,\n  apiKey: process.env.TREBLLE_API_KEY!,\n  // debug: process.env.NODE_ENV !== 'production',\n});\n\nasync function handler(req: NextApiRequest, res: NextApiResponse) {\n  if (req.method === 'GET') return res.status(200).json({ users: [] });\n  return res.status(405).json({ error: 'Method not allowed' });\n}\n\nexport default treblle(handler);\n```\n\nJavaScript version:\n\n```js\nimport { withTrebllePages } from '@treblle/next/integrations/nextjs';\n\nconst treblle = withTrebllePages({\n  sdkToken: process.env.TREBLLE_SDK_TOKEN,\n  apiKey: process.env.TREBLLE_API_KEY,\n});\n\nasync function handler(req, res) {\n  if (req.method === 'GET') return res.status(200).json({ users: [] });\n  return res.status(405).json({ error: 'Method not allowed' });\n}\n\nexport default treblle(handler);\n```\n\n### App Router (app/api)\n\n`app/api/users/route.ts`\n\n```ts\nimport { NextResponse } from 'next/server';\nimport { withTreblle } from '@treblle/next/integrations/nextjs';\n\nconst treblle = withTreblle({\n  sdkToken: process.env.TREBLLE_SDK_TOKEN!,\n  apiKey: process.env.TREBLLE_API_KEY!,\n  // debug: process.env.NODE_ENV !== 'production',\n});\n\nexport const GET = treblle(async () =\u003e {\n  return NextResponse.json({ users: [] });\n});\n\nexport const POST = treblle(async (req: Request) =\u003e {\n  const body = await req.json();\n  return NextResponse.json({ success: true, user: body }, { status: 201 });\n});\n\n// To run on Edge (optional):\n// export const runtime = 'edge';\n```\n\n### Optional: Global Middleware (Edge)\n\nUse only if you want coarse-grained visibility on every request. Middleware can’t read bodies for non‑GET methods, so wrap API handlers for full detail.\n\n```ts\n// middleware.ts\nimport { NextResponse } from 'next/server';\nimport { withTreblleMiddleware } from '@treblle/next/integrations/nextjs';\n\nconst treblle = withTreblleMiddleware({\n  sdkToken: process.env.TREBLLE_SDK_TOKEN!,\n  apiKey: process.env.TREBLLE_API_KEY!,\n  // blocklistPaths: [/^\\/_next\\//, 'static', 'images'],\n});\n\nexport default treblle(async () =\u003e NextResponse.next());\n\n// Limit to API routes (optional):\n// export const config = { matcher: ['/api/:path*'] };\n```\n\n## Configuration\n\nPass these options to `withTreblle`, `withTrebllePages`, or `withTreblleMiddleware`:\n\n- `sdkToken`: Your Treblle SDK token (required)\n- `apiKey`: Your Treblle API key (required)\n- `additionalFieldsToMask`: Extra field names to mask (string[])\n- `blocklistPaths`: Paths to exclude (string prefixes or a RegExp)\n- `ignoreDefaultBlockedPaths`: Disable default static/noise filters (boolean; default `false`)\n- `debug`: Print Treblle errors to console (boolean; default `false`)\n\nExample:\n\n```ts\nconst treblle = withTreblle({\n  sdkToken: process.env.TREBLLE_SDK_TOKEN!,\n  apiKey: process.env.TREBLLE_API_KEY!,\n  additionalFieldsToMask: ['customSecret', 'internalId'],\n  blocklistPaths: ['admin', /^\\/api\\/v1\\/internal/],\n  ignoreDefaultBlockedPaths: false,\n  debug: process.env.NODE_ENV !== 'production',\n});\n```\n\nProduction-only enablement:\n\n```ts\nconst maybeTreblle = process.env.NODE_ENV === 'production'\n  ? withTreblle({ sdkToken: process.env.TREBLLE_SDK_TOKEN!, apiKey: process.env.TREBLLE_API_KEY! })\n  : ((h: any) =\u003e h); // no-op passthrough\n\nexport const GET = maybeTreblle(async () =\u003e NextResponse.json({ ok: true }));\n```\n\n## Defaults\n\n### Masked Fields\n\nAutomatically masked in request/response bodies:\n\n- `password`, `pwd`, `secret`, `password_confirmation`, `passwordConfirmation`\n- `cc`, `card_number`, `cardNumber`, `ccv`\n- `ssn`\n- `credit_score`, `creditScore`\n\nAdd more via `additionalFieldsToMask`.\n\n### Blocked Paths\n\nIgnored by default to reduce noise:\n\n- Files: `favicon.ico`, `robots.txt`, `sitemap.xml`, `manifest.json`, `sw.js`, `service-worker.js`, `browserconfig.xml`, `crossdomain.xml`, `ads.txt`, `apple-touch-icon*`\n- Directories: `/.well-known/`, `/static/`, `/assets/`, `/public/`, `/images/`, `/css/`, `/js`\n- Extensions: `.css`, `.js`, `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.ico`, `.woff`, `.woff2`, `.ttf`, `.eot`\n\nOverride example:\n\n```ts\nignoreDefaultBlockedPaths: true,\nblocklistPaths: ['favicon.ico'],\n```\n\n## Edge Notes\n\n- App Router handlers can opt into Edge with `export const runtime = 'edge'`\n- Middleware runs at the edge; bodies of non‑GET requests are not readable there\n- Prefer wrapping route handlers for full body and error detail\n\n## API Reference\n\n- `withTreblle(config) -\u003e (handler) =\u003e wrappedHandler`\n  - Wraps App Router route method handlers\n- `withTrebllePages(config) -\u003e (handler) =\u003e wrappedHandler`\n  - Wraps Pages Router API handlers\n- `withTreblleMiddleware(config) -\u003e (mw) =\u003e wrappedMiddleware`\n  - Wraps `middleware.ts` for global observation (Edge)\n\nConfig type (informal):\n\n```ts\ntype NextTreblleConfig = {\n  sdkToken: string;\n  apiKey: string;\n  additionalFieldsToMask?: string[];\n  blocklistPaths?: (string | RegExp)[];\n  ignoreDefaultBlockedPaths?: boolean;\n  debug?: boolean;\n};\n```\n\n## Troubleshooting\n\n- Enable logs: set `debug: true` and check server output\n- Verify keys: `sdkToken` and `apiKey` from your Treblle dashboard\n- Start simple: add a `GET /api/health` and hit it\n- Check blocking: ensure your route isn’t blocked by defaults or `blocklistPaths`\n- Edge body missing: use handler wrapping instead of middleware for body capture\n\n## Security Notes\n\n- Store keys in server-only env vars; never use `NEXT_PUBLIC_*`\n- Avoid logging secrets; use `additionalFieldsToMask` for custom sensitive fields\n\n\n## License\n\nMIT © Treblle Inc.\n\n---\n\n### Copy‑Paste Templates\n\nPages Router:\n\n```ts\n// pages/api/hello.ts\nimport type { NextApiRequest, NextApiResponse } from 'next';\nimport { withTrebllePages } from '@treblle/next/integrations/nextjs';\n\nconst treblle = withTrebllePages({\n  sdkToken: process.env.TREBLLE_SDK_TOKEN!,\n  apiKey: process.env.TREBLLE_API_KEY!,\n});\n\nasync function handler(req: NextApiRequest, res: NextApiResponse) {\n  return res.status(200).json({ ok: true });\n}\n\nexport default treblle(handler);\n```\n\nApp Router:\n\n```ts\n// app/api/hello/route.ts\nimport { NextResponse } from 'next/server';\nimport { withTreblle } from '@treblle/next/integrations/nextjs';\n\nconst treblle = withTreblle({\n  sdkToken: process.env.TREBLLE_SDK_TOKEN!,\n  apiKey: process.env.TREBLLE_API_KEY!,\n});\n\nexport const GET = treblle(async () =\u003e NextResponse.json({ ok: true }));\n```\n\nMiddleware (optional):\n\n```ts\n// middleware.ts\nimport { NextResponse } from 'next/server';\nimport { withTreblleMiddleware } from '@treblle/next/integrations/nextjs';\n\nconst treblle = withTreblleMiddleware({\n  sdkToken: process.env.TREBLLE_SDK_TOKEN!,\n  apiKey: process.env.TREBLLE_API_KEY!,\n});\n\nexport default treblle(async () =\u003e NextResponse.next());\n// export const config = { matcher: ['/api/:path*'] };\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftreblle%2Ftreblle-nextjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftreblle%2Ftreblle-nextjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftreblle%2Ftreblle-nextjs/lists"}