Overview

This guide wires Vibenv into an Angular 18 app by attaching a custom webpack config to the serve stage only. Keep your non-dev build targets unchanged, while ng serve runs through a custom webpack dev server that injects Vibenv metadata and the agent script.

1) Configure .npmrc for Vibenv packages

Vibenv ships as scoped packages from the Vibenv registry. Add this to your project-level .npmrc:

@vibenv:registry=https://npm.vibenv.net/

Then authenticate with the Vibenv registry:

npm login --scope @vibenv

Login details will be provided by the Vibenv team.

2) Install dev dependencies

Match the custom webpack builder major version to your Angular major version.

npm install --save-dev @angular-builders/custom-webpack@18 @vibenv/webpack-plugins dotenv

3) Add the Vibenv webpack config

Create vibenv.webpack.config.js at your project root:

const path = require('path');
require('dotenv').config({ path: path.resolve(__dirname, '.env') });
const { AgentEnvProviderWebpackPlugin } = require('@vibenv/webpack-plugins/agent-env-provider-webpack-plugin.js');
const { RelativeAgentWebpackPlugin } = require('@vibenv/webpack-plugins/relative-agent-webpack-plugin.js');
const { attachVibeAgentHandlerToDevServerConfig } = require('@vibenv/webpack-plugins/webpack-vibe-agent-handler-plugin.js');
const { attachVibeServerToDevServerConfig } = require('@vibenv/webpack-plugins/webpack-vibe-server.js');
const angularLoader = require.resolve('@vibenv/webpack-plugins/angular-component-metadata-loader.js');

module.exports = (config) => {
  // Find the @ngtools/webpack rule
  const ngToolsRule = config.module.rules.find(r =>
    r.loader && /@ngtools[\/\\\\]webpack/.test(r.loader)
  );

  if (ngToolsRule) {
    // Convert single loader to array and add our post-loader
    const originalLoader = ngToolsRule.loader;
    delete ngToolsRule.loader;

    ngToolsRule.use = [
      angularLoader,  // Runs LAST (loaders run right-to-left)
      originalLoader
    ];
  }

  config.plugins = config.plugins || [];
  config.plugins.push(
    new AgentEnvProviderWebpackPlugin(),
    new RelativeAgentWebpackPlugin("/vibeagent.js")
  );

  attachVibeServerToDevServerConfig(config);
  attachVibeAgentHandlerToDevServerConfig(config);

  return config;
};

What this does:

• Injects component metadata via angular-component-metadata-loader after @ngtools/webpack emits JS.
• Injects the Vibenv agent script at /vibeagent.js and serves the built bundle from the dev server.
• Mounts the Vibenv dev server routes onto the webpack dev server.

4) Update angular.json to use the custom webpack dev server

@angular-builders/custom-webpack:dev-server reads its webpack config from a custom webpack build target. Keep the default Angular 18 build target unchanged, and add a dedicated build-webpack target for dev server usage.

Imagine your angular.json looks like this:

{
  "projects": {
    "sample-angular-18-ng": {
      "...": "...",
      "architect": {
        "build": "...",
        "serve": "..."
      }
    }
  }
}

Steps:

1. Duplicate the existing build target and name it build-webpack.
2. Change the new builder to @angular-builders/custom-webpack:browser.
3. Add customWebpackConfig.path with ./vibenv.webpack.config.js.
4. Update serve to use @angular-builders/custom-webpack:dev-server and reference build-webpack for the configurations you actually run (for example development and uat).

"build-webpack": {
  "builder": "@angular-builders/custom-webpack:browser",
  "options": {
    "customWebpackConfig": {
      "path": "./vibenv.webpack.config.js"
    }
  }
},
"serve": {
  "builder": "@angular-builders/custom-webpack:dev-server",
  "configurations": {
    "uat": {
      "buildTarget": "sample-angular-18-ng:build-webpack:uat"
    },
    "development": {
      "buildTarget": "sample-angular-18-ng:build-webpack:development"
    }
  },
  "defaultConfiguration": "development"
}

5) Run the dev server

npm run start

You should see vibenv logs in the console during compilation, and the Vibenv overlay should connect once the page loads.

Optional: Set the CLI agent via .vibenv.js

Create .vibenv.js in your project root to control which CLI agent Vibenv uses:

module.exports = {
  "cli-agent": "claude" // or "copilot"
};

This file is read from the current working directory when Vibenv starts.

Notes

• If your app uses a different project name, update the buildTarget strings accordingly.
• dotenv reads from .env in the project root so you can override Vibenv environment variables locally.