Overview

This guide wires Vibenv into an Angular 14 app using a custom Angular builder that integrates with webpack. The custom builder wraps Angular's standard webpack-based build process and injects Vibenv metadata, development server routes, and the agent script.

Note: This integration uses Angular 14's webpack-based build system. For Angular 17+ with esbuild, or Angular 18+ with custom webpack, refer to those specific integration guides.

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

Install the required packages for Angular 14 integration:

npm install --save-dev @vibenv/webpack-plugins @vibenv/angular-builder

The Angular 14 example also includes these standard development dependencies:

npm install --save-dev \
  webpack@^5.75.0 \
  webpack-cli@^5.0.1 \
  webpack-dev-server@^4.11.1 \
  @ngtools/webpack@^14.2.12 \
  fork-ts-checker-webpack-plugin@^7.3.0 \
  eslint-webpack-plugin@^4.0.1 \
  html-webpack-plugin@^5.5.0 \
  tsconfig-paths-webpack-plugin@^4.0.0

3) Create webpack.config.js

Create webpack.config.js at your project root. This config integrates Vibenv's webpack plugins and dev server:

import path from "path";
import webpack from "webpack";
import HtmlWebpackPlugin from "html-webpack-plugin";
import ForkTsCheckerWebpackPlugin from "fork-ts-checker-webpack-plugin";
import ESLintPlugin from "eslint-webpack-plugin";
import { TsconfigPathsPlugin } from "tsconfig-paths-webpack-plugin";
import { AngularWebpackPlugin } from "@ngtools/webpack";
import express from "express";
import { DevAgentWebpackPlugin } from "@vibenv/webpack-plugins/dev-agent-webpack-plugin.js";
import { routes } from "@vibenv/vibe-server/routes.js";
import { logger } from "@vibenv/logger/serverLogger.js";

const webpackConfig = (env) => ({
  entry: "./src/main.ts",
  ...(env.production || !env.development ? {} : { devtool: "eval-source-map" }),
  resolve: {
    extensions: [".ts", ".js"],
    symlinks: false,
    plugins: [new TsconfigPathsPlugin()]
  },
  output: {
    path: path.join(import.meta.dirname, "/dist"),
    filename: "[name].js",
    chunkFilename: "[id].chunk.js"
  },
  module: {
    rules: [
      {
        test: /(?:\.ngfactory\.js|\.ngstyle\.js|\.ts)$/,
        use: [
          {
            loader: "@ngtools/webpack"
          }
        ]
      },
      {
        test: /\.html$/,
        use: "raw-loader"
      },
      {
        test: /\.(scss|css)$/,
        use: ["style-loader", "css-loader", "sass-loader"]
      },
      {
        test: /\.scss$/,
        type: "asset/resource",
        resourceQuery: /ngResource/
      },
      {
        test: /\/assets\//,
        type: "asset"
      }
    ]
  },
  devServer: {
    static: {
      directory: path.join(import.meta.dirname, "src")
    },
    hot: true,
    historyApiFallback: true,
    setupMiddlewares: (middlewares, devServer) => {
      const { app } = devServer;
      app.use(express.json());
      app.use("/_vibe-agent", routes(logger));
      return middlewares;
    }
  },
  plugins: [
    new HtmlWebpackPlugin({
      template: "./src/index.html",
      filename: "./index.html"
    }),
    new webpack.DefinePlugin({
      "process.env.PRODUCTION": env.production || !env.development,
      "process.env.NAME": JSON.stringify(packageJson.name),
      "process.env.VERSION": JSON.stringify(packageJson.version)
    }),
    new ForkTsCheckerWebpackPlugin(),
    new ESLintPlugin({ files: "./src/**/*.{ts,js}" }),
    new AngularWebpackPlugin({
      tsconfig: "./tsconfig.app.json",
      jitMode: true
    }),
    new DevAgentWebpackPlugin()
  ],
  optimization: {
    runtimeChunk: "single",
    splitChunks: {
      chunks: "all",
      maxInitialRequests: Infinity,
      minSize: 20000,
      cacheGroups: {
        vendor: {
          test: /[\\/]node_modules[\\/]/,
          name(module) {
            const packageName = module.context.match(/[\\/]node_modules[\\/](.*?)([\\/]|$)/)[1];
            return `npm.${packageName.replace("@", "")}`;
          }
        }
      }
    }
  }
});

export default webpackConfig;

Key features of this configuration:

• AngularWebpackPlugin: Compiles Angular components with JIT mode
• DevAgentWebpackPlugin: Injects Vibenv's development agent
• Vibe Server Routes: Mounts Vibenv's API at /_vibe-agent
• Code Splitting: Separate vendor bundles for better caching
• Hot Module Replacement: Enabled for development

4) Update angular.json

Update your angular.json to use the custom Vibenv builder:

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "version": 1,
  "projects": {
    "your-app-name": {
      "projectType": "application",
      "root": "",
      "sourceRoot": "src",
      "prefix": "app",
      "architect": {
        "build": {
          "builder": "@vibenv/angular-builder:dev-server",
          "options": {
            "outputPath": "dist",
            "index": "src/index.html",
            "main": "src/main.ts",
            "polyfills": "src/polyfills.ts",
            "tsConfig": "tsconfig.app.json",
            "inlineStyleLanguage": "scss",
            "assets": [
              "src/favicon.ico",
              "src/assets"
            ],
            "styles": [
              "src/styles.scss"
            ],
            "scripts": []
          },
          "configurations": {
            "production": {
              "budgets": [
                {
                  "type": "initial",
                  "maximumWarning": "500kb",
                  "maximumError": "1mb"
                }
              ],
              "fileReplacements": [
                {
                  "replace": "src/environments/environment.ts",
                  "with": "src/environments/environment.prod.ts"
                }
              ],
              "outputHashing": "all"
            },
            "development": {
              "buildOptimizer": false,
              "optimization": false,
              "vendorChunk": true,
              "extractLicenses": false,
              "sourceMap": true,
              "namedChunks": true
            }
          },
          "defaultConfiguration": "production"
        },
        "serve": {
          "builder": "@vibenv/angular-builder:dev-server",
          "configurations": {
            "production": {
              "browserTarget": "your-app-name:build:production"
            },
            "development": {
              "browserTarget": "your-app-name:build:development"
            }
          },
          "defaultConfiguration": "development"
        }
      }
    }
  }
}

Key changes from standard Angular configuration:

1. Both build and serve targets use @vibenv/angular-builder:dev-server
2. The builder integrates webpack with Vibenv's plugins
3. Maintains all standard Angular build options

5) Update package.json scripts

Update your package.json scripts to use webpack directly for builds:

{
  "scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "webpack --mode=production --env production --progress",
    "lint": "eslint \"src/**/*.{ts,js}\"",
    "lint:fix": "eslint \"src/**/*.{ts,js}\" --fix",
    "format": "prettier --write \"src/**/*.{ts,js,html,css,json}\""
  }
}

Note that ng serve still works through the Angular CLI with the custom builder, while the production build uses webpack directly.

6) TypeScript configuration

Ensure your tsconfig.json includes the following:

{
  "compileOnSave": false,
  "compilerOptions": {
    "baseUrl": "./",
    "outDir": "./dist/out-tsc",
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "noImplicitOverride": true,
    "noPropertyAccessFromIndexSignature": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "sourceMap": true,
    "declaration": false,
    "downlevelIteration": true,
    "experimentalDecorators": true,
    "moduleResolution": "node",
    "importHelpers": true,
    "target": "ES2022",
    "module": "ES2022",
    "useDefineForClassFields": false,
    "lib": [
      "ES2022",
      "dom"
    ]
  },
  "angularCompilerOptions": {
    "enableI18nLegacyMessageIdFormat": false,
    "strictInjectionParameters": true,
    "strictInputAccessModifiers": true,
    "strictTemplates": true
  }
}

7) Run the dev server

Start the development server:

npm run start

Or using the Angular CLI:

ng serve

The application will be available at http://localhost:8080.

You should see:

• Vibenv logs in the console during compilation
• The Vibenv overlay connects once the page loads
• Component metadata injection enabled

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.

Complete package.json dependencies

For reference, here's the complete list of dependencies used in the Angular 14 example:

{
  "dependencies": {
    "@angular/common": "^14.2.12",
    "@angular/compiler": "^14.2.12",
    "@angular/core": "^14.2.12",
    "@angular/forms": "^14.2.12",
    "@angular/platform-browser": "^14.2.12",
    "@angular/platform-browser-dynamic": "^14.2.12",
    "@angular/router": "^14.2.12",
    "rxjs": "^7.5.7",
    "tslib": "^2.4.1",
    "zone.js": "^0.12.0"
  },
  "devDependencies": {
    "@angular-devkit/build-angular": "^14.2.10",
    "@angular/compiler-cli": "^14.2.12",
    "@angular-eslint/builder": "^14.4.0",
    "@angular-eslint/eslint-plugin": "^14.4.0",
    "@angular-eslint/eslint-plugin-template": "^14.4.0",
    "@angular-eslint/schematics": "^14.4.0",
    "@angular-eslint/template-parser": "^14.4.0",
    "@types/node": "^18.11.18",
    "@typescript-eslint/eslint-plugin": "^5.48.1",
    "@typescript-eslint/parser": "^5.48.1",
    "eslint": "^8.32.0",
    "eslint-config-prettier": "^8.6.0",
    "eslint-plugin-import": "^2.27.5",
    "eslint-plugin-prettier": "^4.2.1",
    "eslint-webpack-plugin": "^4.0.1",
    "fork-ts-checker-webpack-plugin": "^7.3.0",
    "html-webpack-plugin": "^5.5.0",
    "prettier": "^2.8.3",
    "raw-loader": "^4.0.2",
    "sass": "^1.57.1",
    "sass-loader": "^13.2.0",
    "style-loader": "^3.3.1",
    "tsconfig-paths-webpack-plugin": "^4.0.0",
    "typescript": "~4.8.4",
    "webpack": "^5.75.0",
    "webpack-cli": "^5.0.1",
    "webpack-dev-server": "^4.11.1",
    "@vibenv/vibe-agent": "file:../../src/packages/vibe-agent",
    "@vibenv/framework-plugins": "file:../../src/packages/framework-plugins",
    "@vibenv/logger": "file:../../src/packages/logger",
    "@vibenv/platform": "file:../../src/packages/platform",
    "@vibenv/constants": "file:../../src/packages/constants",
    "@vibenv/swc-plugin": "file:../../src/packages/swc-plugin",
    "@vibenv/transpiler-plugins": "file:../../src/packages/transpiler-plugins",
    "@vibenv/vibe-server": "file:../../src/packages/vibe-server",
    "@vibenv/vite-plugins": "file:../../src/packages/vite-plugins",
    "@vibenv/webpack-plugins": "file:../../src/packages/webpack-plugins",
    "@vibenv/angular-builder": "file:./vibenv-angular-bundler"
  }
}

Troubleshooting

Build fails with module not found errors

Ensure all paths in webpack.config.js are correct and that you're using ES modules (import/export) rather than CommonJS (require/module.exports).

Vibenv overlay doesn't appear

Check that:

1. The DevAgentWebpackPlugin is included in your webpack plugins
2. The dev server middleware is mounting /_vibe-agent routes
3. There are no console errors during build

Angular template compilation errors

Verify that:

1. @ngtools/webpack is properly configured in webpack module rules
2. AngularWebpackPlugin is instantiated with correct tsconfig path
3. JIT mode is enabled if using Angular 14

Hot module replacement not working

Ensure:

1. hot: true is set in devServer configuration
2. webpack-dev-server is installed as a dev dependency
3. You're running ng serve or webpack serve (not webpack --watch)

Notes

• This integration is specifically for Angular 14.x with webpack-based builds
• Angular 17+ uses esbuild by default and requires a different integration approach
• The custom builder wraps Angular's standard webpack builders and passes through most options unchanged
• For production deployments, ensure you're using the production configuration for optimal bundle size and performance
• The Vibenv dev server runs on the same port as your webpack dev server at the /_vibe-agent endpoint

See Also

• Angular 18 Integration (Webpack Dev Server) - For Angular 18+ using custom webpack
• [Vibenv Plugins Overview]((/guide/plugins) - Complete list of available Vibenv plugins