How to Integrate Bolt.new with Mercurial

Before committing to a Mercurial workflow for Bolt projects, it is worth understanding the current state of the Mercurial ecosystem. This context will help you decide whether to proceed with Mercurial or migrate to Git. Mercurial itself is still maintained — the mercurial-scm.org project continues releasing updates, and the core VCS works well for teams that have invested in it. The tool is conceptually simpler than Git in several ways: the mental model of changesets, bookmarks instead of branches for most workflows, and more consistent command behavior across platforms. However, the hosting landscape has changed significantly. Bitbucket dropped Mercurial support in June 2020 — the platform is now Git-only. Organizations that were Bitbucket-Mercurial users had to migrate somewhere: many chose GitHub or GitLab (converting to Git), some set up self-hosted Mercurial servers using RhodeCode or Kallithea, and some moved to Sourcehut (which supports Mercurial natively). For Bolt.new specifically, the decision point is straightforward. If your organization has active Mercurial infrastructure with custom tooling, CI/CD pipelines, and workflows that would be expensive to migrate, the manual export workflow described here is a reasonable solution. If you are starting fresh or could migrate with modest effort, using Git and Bolt's native GitHub integration gives you one-click pushes, automatic deploys via Netlify, and access to the GitHub Actions ecosystem. Most new Bolt users should use GitHub. This guide is for the Mercurial cases where migration is not practical in the short term.

1# Install Mercurial:
2# macOS (Homebrew):
3brew install mercurial
4
5# Ubuntu/Debian:
6sudo apt-get install mercurial
7
8# Verify installation:
9hg --version
10# Should print: Mercurial SCM (version 6.x.x)

Bolt's native GitHub integration (the Git panel) only works with GitHub. For Mercurial, you use the manual export workflow: download the project as a ZIP file from Bolt's toolbar. In your Bolt project, click the download icon in the top toolbar — it typically appears as a downward-pointing arrow or a box with an arrow. Bolt packages your entire project file system (all source files, configuration files, package.json) into a ZIP archive and downloads it to your browser's default download location. Notable items NOT included in the Bolt ZIP export: node_modules/ (correct — you will run hg add and the .hgignore will exclude this), the Bolt Secrets tab values (your API keys and environment variables — you will need to recreate these in a local .env file), and Bolt's internal Version History (this is Bolt's internal undo system, not part of the exported code). After downloading, create an organized folder structure on your local machine for managing Bolt exports. A dedicated directory like ~/projects/bolt-projects/ with a named subfolder for each project works well. Extract the ZIP into this folder, preserving the original project folder structure. Before initializing the Mercurial repository, take a moment to review what was exported by running ls -la in the project directory. You should see standard Vite or Next.js project files: package.json, src/, public/, configuration files (vite.config.ts or next.config.js), and other project-specific files. The presence of package.json is important — it confirms Bolt exported a proper Node.js project that Mercurial (or any VCS) can version control.

1# Create a projects directory and extract the Bolt ZIP:
2mkdir -p ~/projects/bolt-projects/your-project-name
3cd ~/projects/bolt-projects/your-project-name
4
5# On macOS, unzip the downloaded file:
6unzip ~/Downloads/bolt-project-export.zip -d .
7
8# Verify the project structure:
9ls -la
10# Expected: package.json, src/, public/, vite.config.ts or next.config.js

With the Bolt project extracted locally, initialize a Mercurial repository and configure what should be tracked versus ignored. This is similar to how Git uses .gitignore, but Mercurial uses .hgignore with its own pattern syntax. Mercurial's .hgignore file supports two pattern syntax modes: regexp (regular expressions, the default) and glob (shell-style wildcards). For most Bolt project ignores, the glob syntax is more readable and easier to write. Specify the syntax at the top of the .hgignore file. Key directories and files to exclude from Mercurial tracking: node_modules/ (hundreds of megabytes of dependencies — always regenerated by npm install), dist/ and .next/ (build output — always regenerated by npm run build), .env and .env.local (API keys and secrets — never commit these to version control), and .bolt/ (Bolt's internal project metadata if it was included in the export). After creating .hgignore, run hg init to create the Mercurial repository, then hg add to stage all non-ignored files. Review what was staged with hg status — files marked with 'A' are added and will be included in the first commit. If any secret files or large binary files appear in the hg status output, add them to .hgignore before committing.

1# Navigate to the project directory:
2cd ~/projects/bolt-projects/your-project-name
3
4# Create .hgignore:
5cat > .hgignore << 'EOF'
6syntax: glob
7
8# Dependencies (regenerated by npm install)
9node_modules/
10.pnp
11.pnp.js
12
13# Build output (regenerated by npm run build)
14dist/
15build/
16.next/
17out/
18
19# Environment files (contain secrets)
20.env
21.env.local
22.env.development.local
23.env.test.local
24.env.production.local
25
26# Bolt internal
27.bolt/
28
29# macOS
30.DS_Store
31
32# Logs
33npm-debug.log*
34*.log
35EOF
36
37# Initialize Mercurial repository:
38hg init
39
40# Add all non-ignored files:
41hg add
42
43# Review what will be committed:
44hg status

With files staged via hg add, make the initial commit with a descriptive message describing what this Bolt project contains. Then push to your Mercurial hosting platform. For self-hosted Mercurial: Kallithea, RhodeCode, and Gogs (which supports Mercurial) are common choices. Create a new repository on your hosting platform, note the SSH or HTTPS URL, and configure Mercurial's .hg/hgrc file with the remote URL. For Bitbucket alternative (since Bitbucket dropped Mercurial): Sourcehut (sr.ht) is a modern development platform that supports Mercurial natively alongside Git. Create an account at sourcehut.org, set up your SSH key, and push to a Mercurial repository. Sourcehut also has CI (builds.sr.ht) that can run npm run build on pushes. After the initial push, establish a routine for subsequent Bolt updates. When you make changes in Bolt and want to sync them to Mercurial: export a new ZIP from Bolt, extract it to a temporary folder, copy only the changed files over your existing Mercurial repository folder (or use diff/patch to identify and apply changes), then commit and push the updates. This is more manual than Git's approach but achieves the same version control result. An important consideration about the WebContainer limitation: Bolt's development environment cannot receive incoming webhooks or connect to external services using raw TCP. Once you export the project and push to your Mercurial host, any Hg-based CI/CD pipeline can build and deploy the app in a real server environment where these limitations do not apply. Your existing Mercurial-integrated build systems work normally with the exported Bolt code.

1# Make the initial commit:
2hg commit -m "Initial commit: Bolt.new project export"
3
4# Configure remote repository in .hg/hgrc:
5# [paths]
6# default = https://your-hg-host.com/yourname/your-project
7
8# Using a text editor or command line:
9cat >> .hg/hgrc << 'EOF'
10[paths]
11default = https://your-hg-host.com/yourname/your-project
12EOF
13
14# Push to remote:
15hg push
16# For first push you may need:
17hg push --new-branch
18
19# For subsequent Bolt updates:
20# 1. Export new ZIP from Bolt
21# 2. Extract and copy changed files to repo directory
22# 3. Check what changed:
23hg status
24hg diff
25# 4. Commit and push:
26hg commit -m "Update: [describe what changed in Bolt]"
27hg push