Build secrets
Build secrets let your entire workspace securely access private tools and packages while your app is being compiled. They are only available during the build process, never while your published app is running.
Workspace admins on Enterprise plans who need their projects to install private packages or use build-time tools.
Do this, in order
- 1
Navigate to Workspace settings, select Build & deploy, then click Build secrets.
Build secrets are managed across the whole workspace, not inside individual projects.
- 2
Click 'New variable', enter an uppercase name like NPM_TOKEN, paste your secret value, and click 'Save changes'.
The name must match the exact reference in your project files, and the value is permanently hidden after saving.
- 3
In your project chat, ask Lovable to install your private package and mention the exact build secret name.
Lovable will configure the required package files (like .npmrc) to authenticate using your saved secret.
Paste this into your project
Install our private package @acme/ui-components from GitHub Packages. The auth token is in the PACKAGES_TOKEN build secret.
Words decoded
- Build time
- The preparation phase where Lovable downloads components and compiles your code before the app can actually run.
- Runtime
- When the live app is actively running and responding to visitors.
- npm token
- A secure password that allows an automated build system to download private, custom code packages.
- .npmrc
- A small configuration file telling your project where and how to download external packages securely.
Where people get stuck
- Do not put runtime credentials (like Stripe API keys or database keys) in build secrets; use project secrets instead.
- Build secrets cannot be viewed after saving—if you lose track of the value, you must generate a new one and overwrite it.
- You cannot rename a secret after creating it; you have to delete it and create a new one.
- Lovable cannot create or read build secrets on its own; a workspace owner or admin must manually enter them in Workspace settings.
- Build secrets apply to all projects across your entire workspace, not just a single project.
The short version, steps, decoder and prompt on this page are written automatically from Lovable's own documentation and can lag or misread it. The official page is always the authority.