Deploying Bolt.diy with Cloudflare Pages (the easy way!)

[aliasfox]

Last Updated: 4:44 PM 01/03/2025

Let’s dive right in!

There are some dependencies needed to get Bolt.diy⚡ running on your local machine . These are also generally required for building and deployment, but this tutorial will be so EASY, we are going to skip all that noise . We are going to use GitHub Actions to build everything in the cloud . And the best part? Bolt.diy already has mostly everything you need setup for you, with some minor adjustments (basically need to remove a few things and set some flags).

No need to install the latest .NET version (can be an issue on Windows), have Node (npm and pnpm), or even Git. No needing to deal with security or any type of setup . That’s how easy this is going to be. So, follow all steps closely and let’s see who gets to the finish line first!

Prerequisites: There are only three; sign up for a Cloudflare , GitHub, and HuggingFace account if you do not already have them.

They are all completely FREE!

Setting up GitHub

1. Browse to the GitHub page and sign in, or create an account.

2. Browse to the Bolt.diy GitHub Page

3. Click Fork
   

   

4. In the “Create a new fork” dialog, click the “Create fork” button
   

   
   
   Note: Do not check "Copy the main branch only, so we have the ability to switch them later (update). And while you could just sync the stable branch, it’s probably best to pull all of them for the flexibility (for example if you need, or want, to change branches later).

5. A little bit of waiting…
   

6. Click “Code” and browse to “.tool-verions”
   

   

7. Switch to the stable branch from the drop-down.
   Note: in version 0.0.3 Bolt.diy was changed to have a stable branch because main is what PR’s are committed and resolve to.

8. Click on the .tool-version filename to open it and delete the file.
   

   
   
   Notes: this file causes issues with the deployment.

9. Commit the Changes back to your Fork:
   

   

10. Do the same for the wrangler.toml
    

    
    
    
    
    
    Note: Because otherwise Cloudflare will detect it, use it to deploy, and then overwrite the environment variables when we move onto the Cloudflare setup. If you want to deploy without keys, that’s perfectly fine, just note that Bolt.diy does a periodic check whether or not they are set and without them it may not work (not sure if this was changed in the most recent merge). Alternatively, if you used git to clone the repo locally, you could just rename them (but that means more steps).

Setting up Cloudflare⚙️

1. Sign up for, or login to, Cloudflare.

2. In Cloudflare click on “Workers & Pages”
   

3. Click “Create”
   

   

4. Click on “Pages” tab and then “Connect to Git”
   

   
   
   Note: If this is the first time connecting git, Cloudflare will step you through the process and you will need to follow steps to authorize it.

5. Select your GitHub account and Repository (bolt.diy)
   

   

6. Configure “Setup and Deploy” options:
   a. For Framework preset, select "Remix" from the drop-down.
   b. For Build command, we will be modifying this to be:
   npm install pnpm & pnpm install & pnpm run build
   Note: Add your environment variables exactly the way they are listed in your Environment Variables (.env file), see screenshot (you can open the .env.example for reference). And DO NOT include the equals sign in the variable name as that’s intended as the separator between the variable and value (if you do, it will result in caching errors).
   
   WARNING: If you do not use pnpm run build (and leave the default npm run build), then the deployment will appear to work fine, but the page styling will be screwed up. If this happens, it’s fine as you can just modify the build command (and “Retry deployment”, see Steps #12-13) but if you run into a broken page, then you know why.

7. Click the “Setup and Deploy” button
   

   
   
   Note: I did not include the keys in the image for security reasons, but make sure to add them here.

8. Build failed (calm down, it’s fine! It’s fine!³)
   

   
   
   Note: we are not going to use wrangler and because of this the initial deployment will fail with error: Error: Failed to publish your Function. Got error: Uncaught Error: No such module "node:process". imported from "functionsWorker-{cache_hash_key_value}.js"
   Note: In the newest version of Bolt.diy the build may not fail, but just confirm steps 8-10. It appears that something was changed to set the nodejs_compat compatibility flag.

9. Click “Continue to project” and agree to the Warning Prompt:
   

10. Click Settings and scroll down to Runtime
    

    
    
    a. For “Compatibility date”, click edit, select 2024-09-02, and click “Save”
    
    b. For “Compatability flags”, click edit, set to nodejs_compat, and click “Save”
    Note: the option will not be in the drop-down list, you will need to type it in and select the “tag” for it.
    
    c. When you are done, it should look like this:
    
    

11. On “Branch control”, click the edit icon (pen) and change branch to stable
    
    Note: When the article was first written, there was no stable branch, but now this is the recommended branch to use.

12. Click on the “Deployments” tab, then “View Details”:
    

    

13. Click “Retry deployment”
    

    
    
    Note: You could have “triggered” this process simply by modifying a file, committing the changes (or pushed them locally), and it would have re-deployed as well (see Step #14).

14. Wait for it… Success! All Setup and Deployed!
    

    
    
    Note: Due to caching, the page might not load correctly the first time. But don’t worry, if there are no warnings up to this point, let’s continue and give the changes a little time to propagate.

15. Updating (Just an FIY – Nothing to do here!)
    Notes: The project is setup to activate GitHub Actions on Commit/Publish. We just need to modify a file to test it! This event would also be triggered if you did a Commit/Push the usual way on your local machine but we can also setup a schedule to do it for us. But that’s beyond the scope of this tutorial.
    

    
    
    a. Notice if you go back to “code”, the runner was activated!
    
    
    
    b. Success on change.
    
    
    
    c. Now you can sync the fork, but just remember to delete or blank out the .tool-versions, and wrangler.toml if they get re-created (not sure they will, I haven’t tested this yet).
    
    

16. Now lets check out our new deployment:
    

    

17. It’s alive!!! It works, and it costed nothing but a little time!!
    

    
    
    And now you have your own Bolt.diy to play with and share!

Optional Steps:

Setup a Custom URL

1. If you already have a Domain name setup on Cloudflare, just provide the subdomain and the tool will take care of the rest for you (DNS records, etc.).
   
   
2. Let Cloudflare do the work and click “Activate domain”
   
   
3. Wait a few minutes, and done.

Updating Bolt.diy Deployment on Change

1. Go to your forked GitHub repo, change branch to “Stable” (or which ever one you are updating), and click the “Sync fork” dropdown"
   

   

2. Click on “Update branch” in the dropdown:
   Note: Do not click “Discard X commits” and then you don’t need to delete the .tool-versions and wrangler.toml files each time.
   

   

3. Done.
   Notice that updating the branch automatically trigger the Cloudflare Pages to re-build and deploy (there’s nothing else to do, just wait):
   

   
   
   
   
   
   Note: You can also setup a GitHub action to do this automatically and just keep the repo up to date on change, but I haven’t created documentation for this yet. It’s honestly not that hard either and just keeps me from having to do it manually (or even remembering to).

TBD:

• User Authentication through Cloudflare Zero Trust
• Automatically update deployment through GitHub Actions.
• Connecting Local Models (Ollama, LMStudio, etc.) to Cloudflare Pages Deployment
• Integrating Supabase to Cloudflare Pages Deployment

Troubleshooting:

• Bolt.diy page styling is jacked up, you get a module error, vite missing, then you used npm install at some point and/or did not update the build command. Check the instructions!
• Error: pnpm plugin is not installed? You did not remove the .tool-versions and/or wrangler.toml from your forked repo. See comment #108
• There are some known issues with Safari that cause a bunch of cache errors. Try Chrome/Edge/Firefox. No known fix yet. See comment #91 and #131.
• Error message after following guide? Likely did not change branch to stable. Check instructions for details and comment #76.
• Want to secure your Cloudflare Pages Deployment down, see comment #61
• Make sure there are not equals signs in your environment variables
• Make sure to set the compatability_flags date and nodejs_compat
• Ensure you are using the stable branch (see latest docs)

Last Steps: Test your Deployment

• Open the URL (either generated or Custom) and test that everything works.
• Please let me know if you run into issues and I can create a troubleshooting guide.
• We would all appreciate you dropping an issue item through the GitHub page, please just see if the issue already exists first.

Final Thoughts
This tutorial hopefully seems straight-forward but it took a lot of testing and process refining because there was really no good documentation on this. Hope it works for you, and you simply appreciate the effort (show some love – bookmark🔖 and give a heart❤️‍).

There will likely be updates to this tutorial in the future.

Thanks!

P.S. A PDF Version is available through my google drive (I’ll manage versions through there, so the link will always be the latest one).

[ColeMedin]

@aliasfox This is INCREDIBLE! Thank you so much for putting the time into creating this for everyone. I am definitely going to feature this along with @dustinwloring1988’s guides in my next video on bolt.diy

[wonderwhy.er]

Hm, I wonder if we can make this easier, that is quite a long things

[aliasfox]

Actually, I think it’s just very verbose. I wanted to leave no room for ambiguity. I provided step by step with a lot of screenshots (like before/after). It seems like a lot, but it’s not (when you actually do it). I can deploy a new instance in ~5 minutes. And the alternative of setting up prerequisites, downloading to your machine, installing packages, deploying from there, and having to troubleshoot issues (and it doesn’t even work ideally) I find is a bit more cumbersome.

A possible way to handle the length might be to split up certain steps into their own standalone docs (like using Custom URLs) and including the references as text links. I had also hoped to remove steps 6-9 of the GitHub steps, and 8-13 of Cloudflare steps, to be taken care of a single step (instead of 8), adding to the “Build command”, but the problem is the order they run in prevents this from being an option.

And some people may not particularly care about it being automated (re-builds itself on Repo change), but I personally think that’s the remarkable bit, so those steps could also be extracted. Another article I am working on is how to automate it getting the latest updates from the Stable Bolt.diy branch and re-building on a schedule. And that’s really just a few steps because the action I created is dynamic; the only caveat is that you have to setup a GitHub PAT (Personal Access Token).

But as far as refinement, it’s as straight forward as it can get at this point in time. Also, updates to the repo may improve this.

[wonderwhy.er]

I mean you are doing some things like deleting files.

I wonder ifvwe can make changes in repo to make it simpler.

[aliasfox]

I don’t even know what the .tool-versions actually does, but it causes the deployment to fail due to pnpm requirements (issue caused by execution order but I still don’t know what it does).

Wrangler.toml is in theory useful because it helps you deploy to Cloudflare and it’s pretty cool, but you lose the auto re-deploy aspect of it and it locks down your API keys to managed by it. And if you update it, you don’t want it to be committed with your repo (with plain-text keys). Another option is for Cloudflare to simply detect the Wrangler.toml file and do everything for you (which it does, hence removing it), but it 1) locks the keys, 2) would require you to put your keys in the TOML file, and 3) it reduces your ability customization anything. But maybe you could manage your keys as variables or secrets somewhere and the TOML file be made generic to reference these (was a thought I had but it needs further exploration). This would reduce everything to a handful of steps.

In theory, it be best if you could just fork Bolt.diy and not have to modify a thing (and deploy either way, keeping all “features”).

[wonderwhy.er]

I was thinking to make automatic deploys from PRs for main repo before.
So that we have deployed link for PR to test and do not need to check out and build locally to test.

Would make reviewing PRs faster.

[Wazzup]

Hi!

I am having this error:
Failed: an internal error occurred. If this continues, contact support: https://cfl.re/3WgEyrH

This happened when I added the variables and secrets. If I delete them, the build is successful, if not it will always fail.

==UPDATE==
Fixed now, my bad. I included the = sign. haha

[Wazzup]

my next question will be, how do I lock this? that only me can access it?

[aliasfox]

Awesome, so the process worked well for you? Thanks!

[aliasfox]

Would require some modifying of the code for something like OAuth. A hacky away might just be to use an htacess file, but I’d have to work through this, so I couldn’t say off the to of my head.

Maybe that will be a future tutorial to add into it.

I’m have one in drafts current, for automating getting updates from the Bolt.diy “Stable” branch, so it just keeps itself up to date. It’s pretty simple but requires a little more testing.

[aliasfox]

I was thinking something similar, maybe we should discuss. I was thinking of an all in one tool for PR’s though. Would definitely help with testing.

[renzomogra]

Hey there! I did all the steps until step 15.

I’m getting this error in the production link:

_@https://96b809e3.bolt-diy-e8k.pages.dev/assets/_index-BWi2qJjP.js:1:1124
Mu@https://96b809e3.bolt-diy-e8k.pages.dev/assets/components-6Yp278Dk.js:38:16998
dh@https://96b809e3.bolt-diy-e8k.pages.dev/assets/components-6Yp278Dk.js:40:43920
sh@https://96b809e3.bolt-diy-e8k.pages.dev/assets/components-6Yp278Dk.js:40:39692
Fv@https://96b809e3.bolt-diy-e8k.pages.dev/assets/components-6Yp278Dk.js:40:39620
Bi@https://96b809e3.bolt-diy-e8k.pages.dev/assets/components-6Yp278Dk.js:40:39474
Ka@https://96b809e3.bolt-diy-e8k.pages.dev/assets/components-6Yp278Dk.js:40:35853
oh@https://96b809e3.bolt-diy-e8k.pages.dev/assets/components-6Yp278Dk.js:40:34804
_@https://96b809e3.bolt-diy-e8k.pages.dev/assets/components-6Yp278Dk.js:25:1570
G@https://96b809e3.bolt-diy-e8k.pages.dev/assets/components-6Yp278Dk.js:25:1938

I only added 3 APIS: Claude, Hugging Face and OpenAI,

am I missing something?

[GKannan]

It’s easy to limit access with Cloudflare Zero Trust Add web applications · Cloudflare Zero Trust docs

[renzomogra]

After a few minutes it now works, lol! I did nothing and now the interface showed up, but, when I select a model, for example, Claude it shows: Not set (will still work if set in .env file)

But I stablished the API key in the cloudflare terminal, should I do it again?

[kdarius0]

i just found this error, could anyone help me

[GKannan]

It looks like Cloudflare error, can you retry the deployment?

[Wazzup]

yes. works now. but I experienced that AI just gets stuck and wort work after that. So needs to start a new task and it works again. I’m not sure if this is because it’s running in cloudflare. I am using google gemini 2 and X grok ai, both AI encountered issues mid coding.

[aliasfox]

@renzomogra

Claude, Hugging Face and OpenAI,

It’s misleading but that’s what it says. If you have the API keys named correctly and set, despite that message they will still work. If you don’t set them (what that message is meant for) then the user can in the front-end. It can be a little misleading and things like that should eventually get resolved.

As for the issues you ran into, I think it has to do with setup, caching and whatnot on the first go. I mentioned that in the tutorial, that you should just move on to the next step because it won’t be ready right away. Glad to see it’s working for you though.

Everything end up working? Or are you still having issues?

Thanks

[aliasfox]

If you are still having this issue, try to re-deploy, download the logs and PM them to me? Could have just been a que thing, idk. I need more info. Thanks!