Skip to main content
Version: 4.6.1-saas

Installation and Initialization

This guide explains the installation and initialization process for the NetFUNNEL Node.js agent.

Step 1: Install Package​

Add Dependencies​

Add the following dependencies to package.json. The exact URL can be found in the Agent tab of the console.

{
  "dependencies": {
    "netfunnel-node-agent": "{{AGENT_URL}}"
  }
}

Install Package​

Run the following command from the project root:

npm install

Step 2: Get Client ID and Secret Key​

  1. Go to NetFUNNEL Console
  2. Click the profile icon in the top right corner
  3. Select the Integration Credentials menu
  4. Copy Client ID and Secret Key
Client ID and Secret Key Location

You can find them in the Integration Credentials menu after clicking the profile icon in the top right corner of the console screen.

Step 3: Apply Middleware​

Apply NetFUNNEL logic to the middleware that receives server requests first. Choose the method that fits your project structure between Express and Nuxt.

Express Middleware Application Method​

1. Create Middleware​

Create middleware/netfunnel-middleware.ts file:

import { Netfunnel } from 'netfunnel-node-agent';

export function netfunnelMiddleware(req, res, next) {
  Netfunnel.run(req, res).then(allowed => {
    if (!allowed) {
      return res.redirect(302, req._nfRedirect || '/');
    }
    next();
  });
}

2. Register Middleware in App​

Initialize NetFUNNEL and register middleware in app.ts:

import express from 'express';
import { router } from './routes.js';
import { netfunnelMiddleware } from './middleware/netfunnel-middleware.js';
import { Netfunnel } from 'netfunnel-node-agent';

const app = express();
const PORT = 3000;

/* NetFUNNEL Global Initialization */
Netfunnel.initialize({
  clientId: '{{CLIENT_ID}}',  // Client ID obtained in Step 2
  secretKey: '{{SECRET_KEY}}'  // Secret Key obtained in Step 2
});

app.use(netfunnelMiddleware);
app.use('/', router);

app.listen(PORT, () => {
  console.log(`[APP] listening on ${PORT} (NetFUNNEL ${Netfunnel.getVersion()})`);
});

Register NetFUNNEL middleware globally to apply queue control to all requests.

Nuxt Middleware Application Method​

1. Create Middleware​

Create server/middleware/netfunnelAgent.ts file:

import { sendRedirect } from 'h3';
import { Netfunnel } from 'netfunnel-node-agent';

export default defineEventHandler(async event => {
  Netfunnel.initialize({
    clientId: '{{CLIENT_ID}}',  // Client ID obtained in Step 2
    secretKey: '{{SECRET_KEY}}'  // Secret Key obtained in Step 2
  });
  
  console.log('[APP] NetFUNNEL Version:', Netfunnel.getVersion());
  
  const allowed = await Netfunnel.run(event.node.req, event.node.res);
  
  if (!allowed) {
    const redirectUrl = (event.node.req as any)._nfRedirect || '/';
    console.log(`Redirecting now to: ${redirectUrl}`);
    return sendRedirect(event, redirectUrl);
  }
});

In Nuxt 3, register the NetFUNNEL agent through defineEventHandler. After calling Netfunnel.run(), if allowed is false, it redirects to the redirect URL after entering the waiting room, otherwise it continues with routing processing. Unlike Express, no next() call is needed.

Step 4: Initialization Settings​

For detailed information about initialization settings, refer to the Initialization Settings document.

Basic Initialization Example​

Netfunnel.initialize({
  clientId: '{{CLIENT_ID}}',
  secretKey: '{{SECRET_KEY}}'
});

Step 5: Verify Installation​

To verify that the agent is installed correctly, check the following:

  1. Package Installation Check: Verify that the netfunnel-node-agent package is correctly installed
  2. Initialization Success: No errors should occur when starting the server
  3. Middleware Application: Verify that requests are processed correctly

Troubleshooting​

Package Installation Failure:

  • Verify that the dependency path in package.json is correct
  • Check the exact URL in the Agent tab of the console
  • Check network connection

Initialization Failure:

  • Verify that clientId and secretKey are correctly set
  • Verify that they are not empty strings

Middleware Not Working:

  • Verify that middleware is correctly registered
  • For Express, check the order of app.use()
  • For Nuxt, verify that the file is correctly located in the server/middleware/ folder

Next Steps​