Using External Libraries in Lovable Without Errors

Why external libraries sometimes break in Lovable projects

Lovable projects use Vite as the build system, which bundles npm packages for the browser. Most popular React-compatible packages work out of the box when you ask Lovable to install them. However, some packages are designed for Node.js server environments and use APIs that do not exist in browsers — like 'fs' (file system), 'path', 'crypto', or raw TCP sockets. When Lovable installs a Node.js-only package, the build may succeed but the app crashes at runtime with errors like 'Module not found: fs' or 'process is not defined.' Other times, a package works initially but conflicts with an existing dependency version, causing subtle bugs or build failures. Lovable does not have a terminal, so you cannot run npm install manually. Instead, you tell the AI which package to use and it handles the installation through the prompt. This works well for most packages, but you need to know how to troubleshoot when things go wrong — especially with packages that require post-install configuration, peer dependencies, or special Vite plugins.

• Package requires Node.js APIs not available in browsers — fs, path, child_process, net
• Version conflict with existing dependencies — the new package needs a different version of React or another shared dependency
• Missing peer dependencies — the package requires additional packages that were not installed automatically
• Package requires Vite plugin configuration — some packages need entries in vite.config.ts to work with the bundler
• Private package without authentication — npm registry rejects the install because no auth token is configured

Error messages you might see

Before you start

• A Lovable project open in the editor
• The name of the npm package you want to use (check npmjs.com for browser compatibility)
• For private packages: your npm authentication token from your npm account or organization

How to fix it

// Vague prompt — Lovable might pick the wrong package
// "Add charts to my dashboard"

// Specific prompt — Lovable installs exactly what you want
// "Use the recharts npm package to add a line chart to
//  @src/pages/Dashboard.tsx showing monthly revenue data.
//  The chart should use the ResponsiveContainer component
//  and display data from the revenue_data state variable."

// Node.js-only package — will crash in browser
import { readFileSync } from "fs";
import { join } from "path";
const config = JSON.parse(readFileSync(join(__dirname, "config.json"), "utf-8"));

// Browser-compatible alternative — fetch config from API or use static import
const config = {
  apiUrl: import.meta.env.VITE_API_URL || "https://api.example.com",
  maxRetries: 3,
};
// Or fetch from a Supabase Edge Function if config is dynamic
import { supabase } from "@/integrations/supabase/client";
const { data: config } = await supabase.functions.invoke("get-config");

// Lovable tries to install the latest version which conflicts
// Error: ERESOLVE unable to resolve dependency tree
// peer dep requires react@^18.0.0 but found react@17.0.2

// Ask Lovable to install a compatible version
// "Install @hello-pangea/dnd version 16.5.0 which supports React 17.
//  This is a maintained fork of react-beautiful-dnd that works
//  with the React version in my Lovable project."
// Or in the prompt:
// "Update my project to use the latest React version first,
//  then install the chart library"

// Build fails because private package requires authentication
// npm ERR! 404 Not Found - @your-org/design-system

// 1. Go to Workspace Settings → Build Secrets
// 2. Add: NPM_TOKEN = your-npm-auth-token
//
// Lovable automatically creates a .npmrc during build:
// //registry.npmjs.org/:_authToken=${NPM_TOKEN}
//
// Now private packages install successfully during build

Complete code example

1import { LineChart, Line, XAxis, YAxis, CartesianGrid, Tooltip, ResponsiveContainer } from "recharts";
2import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
3
4// Sample data — replace with your actual data source
5const revenueData = [
6  { month: "Jan", revenue: 4000 },
7  { month: "Feb", revenue: 3000 },
8  { month: "Mar", revenue: 5000 },
9  { month: "Apr", revenue: 4500 },
10  { month: "May", revenue: 6000 },
11  { month: "Jun", revenue: 5500 },
12];
13
14export default function ChartDashboard() {
15  return (
16    <Card>
17      <CardHeader>
18        <CardTitle>Monthly Revenue</CardTitle>
19      </CardHeader>
20      <CardContent>
21        {/* ResponsiveContainer makes the chart adapt to parent width */}
22        <ResponsiveContainer width="100%" height={300}>
23          <LineChart data={revenueData}>
24            <CartesianGrid strokeDasharray="3 3" />
25            <XAxis dataKey="month" />
26            <YAxis />
27            <Tooltip />
28            <Line
29              type="monotone"
30              dataKey="revenue"
31              stroke="#8884d8"
32              strokeWidth={2}
33              // Smooth animation when data changes
34              animationDuration={300}
35            />
36          </LineChart>
37        </ResponsiveContainer>
38      </CardContent>
39    </Card>
40  );
41}

Best practices to prevent this

• Always name the exact npm package in your prompt — do not say 'add a chart library,' say 'use the recharts npm package'
• Check the package's npm page for browser compatibility before requesting installation — look for 'browser' or 'module' field
• Use well-maintained, popular packages — they are more likely to work with Vite and have good browser support
• Pin specific versions when you encounter peer dependency conflicts — ask Lovable to install a compatible version
• For private packages, add your NPM_TOKEN in Workspace Settings, then Build Secrets before requesting the install
• If a package needs a Vite plugin, mention it in your prompt: 'Install the package and add its Vite plugin to vite.config.ts'
• Test the package in the preview immediately after installation — do not add more features on top before verifying it works
• Keep a list of packages your project uses in AGENTS.md so the AI knows what is already installed

Still stuck?

Copy one of these prompts to get a personalized, step-by-step explanation.

Related error patterns