Treblle with NodeJS
Requirements
- Node.js
Dependencies
Installation
You can install Treblle for Node via NPM. Simply run the following command:
$ npm install treblle
Don’t forget to load the required JavaScript modules in your app.js
like so:
const express = require('express')const { useTreblle } = require('treblle')
Getting started
Next, create a free account on treblle.com to get an API key and Project ID. After you have those simply initialize Treblle in your app.js
file like so for Express:
const app = express()app.use(express.json())
useTreblle(app, { apiKey: '_YOUR_API_KEY_', projectId: '_YOUR_PROJECT_ID_',})
That’s it. Your API requests and responses are now being sent to your Treblle project. Just by adding that line of code you get features like: auto-documentation, real-time request/response monitoring, error tracking and so much more.
One thing that you need to bear in mind is that express will use first in first out when it comes to middleware. So if you want Treblle to capture unfiltered/altered request and response data, then it needs to be the first middleware in your middleware pipeline.
Koa integration
If you’re using koa, then you can enable Treblle like this:
const Koa = require('koa')const KoaRouter = require('koa-router')const KoaBody = require('koa-body')const { koaTreblle } = require('treblle')
const app = new Koa()const router = new KoaRouter()
app.use( koaTreblle({ apiKey: '_YOUR_API_KEY_', projectId: '_YOUR_PROJECT_ID_', }))
Strapi integration
This integration is for Strapi v3, for Strapi v4 check out this integraion guide instead
Treblle has support for Strapi as well, to start using it you need to define the middleware first and then enable the middleware.
This guide is based on the strapi quickstart project, you can create it and follow by running the following command:
npx create-strapi-app my-project --quickstart
First define the middleware in middlewares/treblle/index.js
like this:
const { strapiTreblle } = require('treblle')
module.exports = (strapi) => { return { initialize() { strapi.app.use( strapiTreblle({ apiKey: '_YOUR_API_KEY_', projectId: '_YOUR_PROJECT_ID_', }) ) }, }}
Then enable the Treblle middleware in config/middleware.js
like this:
module.exports = { settings: { treblle: { enabled: true, }, },}
Cloudflare Workers integration
Service workers
To use external packages (like Treblle) inside your workers you need a bundler (eg. Webpack or Rollup) to gather all dependencies into a single file which can be then deployed to Cloudflare. Read more about it in Cloudflare webpack & configuration official documentation, and in an official example.
Example - Wrangler’s webpack
...type = "webpack"webpack_config = "webpack.config.js"
[build.upload]format = "service-worker"
module.exports = { entry: './index.js', target: 'webworker', mode: 'production', output: { filename: 'worker.js', },}
const { serviceWorkerTreblle } = require('treblle')
// Call this function for initialization, Treblle will attach itself to the 'fetch' event to be able to listen for responseconst treblle = serviceWorkerTreblle({ apiKey: '_YOUR_API_KEY_', projectId: '_YOUR_PROJECT_ID_', additionalFieldsToMask: ['key1', 'key2'], // Optional showErrors: true, // Optional, defaults to true})
// Wrap your 'fetch' handler inside returned Treblle function, so Treblle can listen for unhandled application errors in your codeaddEventListener( 'fetch', treblle((event) => { event.respondWith( new Response('Hello worker!', { headers: { 'content-type': 'text/plain' }, }) ) }))
Module workers
Similar as with Service workers above, you need a bundler to package Treblle SDK together with your application code. Be sure to check out official Cloudflare documentation about webpack & modules configuration if you are stuck.
Here is also an official example of a setup with both Modules and CommonJS, using Webpack: link.
Example
import { moduleWorkerTreblle } from 'treblle'
// Initialize Treblle with this function, and store Treblle wrapper inside a variableconst treblle = moduleWorkerTreblle({ apiKey: '_YOUR_API_KEY_', projectId: '_YOUR_PROJECT_ID_', additionalFieldsToMask: ['key1', 'key2'], // Optional showErrors: true, // Optional, defaults to true})
export default { // Wrap your 'fetch' handlers inside Treblle wrapper function to use it fetch: treblle(async (request) => { return new Response(JSON.stringify({ sample: 'json' }), { headers: { 'content-type': 'application/json' }, }) }),}
Important Note
Treblle package (currently) uses some Node native libraries for other integrations, like os
& url
, which are not supported in Cloudflare Workers Runtime. They are not used in this integration, so it is enough to polyfil them with empty modules.
... resolve: { fallback: { os: false, url: false } }...
NestJS (with Express)
// NestJS's boostrap functionconst { useNestTreblle } = require("treblle");const app = await NestFactory.create(AppModule);
...
const expressInstance = app.getHttpAdapter().getInstance();
useNestTreblle(expressInstance, { apiKey: "_YOUR_API_KEY_", projectId: "_YOUR_PROJECT_ID_",});
...
Running Treblle only in production
If you want to run Treblle only in production, you can rely on the environment variables, or use a similar approach via your app config.
const app = express()app.use(express.json())
if (process.env.NODE_ENV === 'production') { useTreblle(app, { apiKey: '_YOUR_API_KEY_', projectId: '_YOUR_PROJECT_ID_', })}
Need to hide additional fields?
If you want to expand the list of fields you want to hide, you can pass property names you want to hide by using the additionalFieldsToMask
setting like in the example below.
useTreblle(app, { apiKey: '_YOUR_API_KEY_', projectId: '_YOUR_PROJECT_ID_', additionalFieldsToMask: ['secretField', 'highlySensitiveField'],})
Logging errors
For easier debugging when sending the data to Treblle errors are visible by default, you can control it via the showErrors
flag, you can disable the errors with showErrors
set to false
:
useTreblle(app, { apiKey: '_YOUR_API_KEY_', projectId: '_YOUR_PROJECT_ID_', showErrors: false,})