Create a Local Environment From a Lovable Project

Before you start: what you need ready

Local setup fails most often because of a missing .env file, a wrong Node.js version, or a GitHub repo that has not been connected yet. Check every item on this list before running your first npm install — it saves 30 minutes of debugging a problem that is actually a prerequisite.

1. Check Node.js version: node --version. You need 18 or higher. Install with nvm: nvm install 18 && nvm use 18.
2. Check Git: git --version. Install from git-scm.com if missing.
3. Check npm or pnpm: npm --version. npm ships with Node; install pnpm separately if your project uses it.
4. Connect Lovable to GitHub: Project Settings → GitHub → Connect and Push. The repo must exist before you can clone.
5. Copy your Supabase credentials from Lovable Project Settings → Environment: VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY.
6. Note any other VITE_ variables — list everything in Project Settings → Environment before closing the tab.

How does local development compare to running in the Lovable editor?

The Lovable editor runs in the cloud and bills by AI credit. A local dev environment runs on your machine, has no per-prompt cost, lets you use any IDE, and gives you full terminal and debugger access. The trade-off is the initial setup time and the need to manage Node.js versions yourself.

How do I clone the repo and install dependencies?

Once the repo exists on GitHub, clone it and run npm install. Lovable projects use Vite as the build tool, so the local dev server command is npm run dev. The first install may take a minute or two depending on your connection speed and the number of dependencies in the project.

1. git clone https://github.com/<your-username>/<repo-name>.git
2. cd <repo-name>
3. npm install
4. If you see peer dependency warnings, they are usually safe to ignore — do not run npm install --force unless you understand what it changes.

How do I set up the .env file for local development?

Create a .env file in the project root with your Supabase credentials. Lovable uses Vite, which reads variables prefixed with VITE_ from the .env file at build time. Do not commit this file to GitHub — it is usually already listed in .gitignore, but confirm before your first commit.

1. In the project root, create a file named .env (not .env.txt or .env.local unless your vite.config.ts specifies it).
2. Add: VITE_SUPABASE_URL=https://<your-ref>.supabase.co
3. Add: VITE_SUPABASE_ANON_KEY=<your-anon-key>
4. Add any other VITE_ variables from Lovable Project Settings.
5. Confirm .env is listed in .gitignore before committing.

How do I start the local dev server?

Run npm run dev from the project root. Vite starts a local server at http://localhost:5173 by default (the port may vary if 5173 is in use). The dev server has hot-reload — changes to your files appear in the browser within a second without a full page refresh, which makes local development much faster than iterating in the Lovable editor.

1. npm run dev
2. Open http://localhost:5173 in your browser.
3. If the port differs, check the terminal output — Vite prints the exact URL.
4. Test a Supabase read to confirm env vars are loaded correctly.

Common local setup errors and fixes

Most local setup failures fall into four categories: missing .env file, wrong Node.js version, unresolved path aliases, and npm permission errors on Mac. The table below maps each symptom to its cause and the fastest fix — check these before spending time in Stack Overflow.

What are the most common errors when running a Lovable app locally?

The three most common errors are: Supabase client not initialising (missing .env file or wrong variable names), Node version mismatch causing build errors (fix with nvm use 18), and a missing vite.config.ts alias for @ imports that causes module-not-found errors. Each has a straightforward fix — check the error message in the terminal before reaching for npm install --force.

Missing @ alias: check vite.config.ts for resolve.alias. Lovable projects usually have { '@': path.resolve(__dirname, './src') } but occasionally it is missing. Add it manually and restart the dev server.

If npm install fails with an EACCES error on Mac, you have an npm permissions issue — do not use sudo npm install. Instead, fix npm's directory permissions or use nvm, which installs Node per-user and avoids permission conflicts.

How do I add localhost to Supabase allowed origins?

Supabase auth restricts which origins can sign in users. Your production Supabase project does not include localhost by default, so sign-in from the local dev server fails silently. You need to add the local URL to Supabase's allowed origins, but be careful not to leave it there permanently in a production project.

1. In the Supabase dashboard, go to Authentication → URL Configuration.
2. Add http://localhost:5173 to the Redirect URLs list (use the exact port Vite is running on).
3. Save and return to your local dev server — auth should now work.
4. If you want to avoid modifying your production Supabase project, create a separate Supabase project for local development and use its credentials in your .env file.

Can I commit changes locally and push them back to Lovable?

Yes. Once your local changes are committed and pushed to the GitHub branch Lovable is watching, the Lovable editor reflects the new code. This lets you use a proper IDE locally for complex refactors, then return to Lovable's AI editor for feature additions. It is the most productive workflow for teams that want AI speed without giving up engineering control.

1. Make your changes in the local codebase.
2. git add <files> && git commit -m 'your message'
3. git push origin main
4. Open the Lovable editor — it should reflect the pushed changes.

How do I roll back a local change that breaks the app?

Because you are using git locally, rolling back a bad change is one command. If a change broke something and you want to get back to a known-good state, use git stash or git revert. Do not use git reset --hard on a branch that Lovable is also committing to — it will create conflicts when Lovable pushes its next change.

1. To discard uncommitted changes: git stash (saves them) or git checkout -- <file> (discards one file).
2. To revert the last commit without losing the change permanently: git revert HEAD.
3. To go back to the last known-good remote state: git fetch origin && git reset --hard origin/main.
4. After any reset, run npm install again to ensure dependencies match the reverted package.json.