Skip to main content

​
🚀 Introduction

  • The Bun runtime is an alternative JavaScript runtime you can choose for your project. If you don’t have Bun installed locally yet, you have two main options:
  • Install via npm (recommended to ensure npx bun is available during deploy): 
npm install bun
  • Or install Bun with the official native installer (check Bun’s docs for instructions).
  • By adding bun as a dependency you can use npx bun in the START field of your squarecloud.app to run your app with Bun. See the “Starting the Application” section below for START examples.
  • Next, you’ll need to create a Square Cloud account via the login page. You can sign up with your email, GitHub, or both.
  • Finally, you must have an active paid plan on your account. You can view and purchase plans here.

​
⚙️ Creating the squarecloud configuration file

Learn more: how to create the configuration file for Square Cloud.

The squarecloud.app file is a configuration file used to configure your application; it defines the name, description, version, main file, and more.

​
▶️ Starting the Application

  • To use the Bun runtime on Square Cloud, add the bun package to your project (for example npm install bun) so the npx bun command is available in the runtime environment.
  • Then set the START field in your squarecloud.app to the command that starts your app using Bun. Example:
OR .config
START=npx bun main.js
Alternately, if you need to run package.json scripts with Bun, use: 
START=npx bun run start
  • Remember: if the START field is defined, its value will be executed directly. For more information about configuration file parameters, visit configuration parameters.
  • If the node_modules folder is not present, Square Cloud will run: 
npm install --no-package-lock --no-audit --no-fund
to install dependencies and clean the .npm folder. If you plan to use Bun as the runtime, we recommend adding bun as a dependency (npm install bun) to ensure npx bun is available during deploy. If you prefer Bun’s native installer, check compatibility and build requirements before choosing that approach.

​
🖥️ Preparing your Bun project

​
📁 Essential configuration files

When preparing your Bun project for deploy on Square Cloud, make sure to include the configuration file (squarecloud.app/.config) and your application’s essential files inside a zip archive.
The configuration file (squarecloud.app/.config) must be located at the root of the zip file. Otherwise, Square Cloud will not be able to find it during deployment.

​
🗑️ Files to exclude before upload

  • node_modules: This folder does not need to be uploaded because it will be recreated during production install.
  • package-lock.json: This file is not required because the production environment will install dependencies based on package.json.

​
🤔 Why exclude these files?

There are several reasons to exclude node_modules and package-lock.json before uploading your project:
  1. Consistent installs: Not uploading node_modules ensures dependencies are installed by the production environment, resulting in a consistent build free from local system discrepancies.
  2. Updated installations: The production environment will install compatible, up-to-date versions of dependencies listed in package.json, providing a clean start for your app.
  3. Reduced upload size: Excluding these folders reduces the upload size, speeding up upload and deployment.
Doing so helps ensure your Bun application is optimized for hosting on Square Cloud.

​
📄 Required files

The following files are required to host your Bun project:

​
💡 Troubleshooting

This error occurs when the file defined as “main” for your application in the configuration file does not exist, is written incorrectly, or the path is incorrect. If your main file is inside a folder, for example, you should enter folder/file.js.
The minimum amount of RAM required to host a bot is 256MB, and for a website/API, it’s 512MB. However, depending on the size and complexity of your application, it may be advisable to allocate a larger amount of RAM to avoid the LACK_OF_RAM error.

​
📤 Uploading Project to Square Cloud

After preparing your project files, you can now upload them to Square Cloud and host your project.
  • Dashboard Upload
  • CLI Upload
Access the Square Cloud Dashboard and upload your project files.
If you continue facing technical difficulties, our specialized support team is available to assist you. Contact us and we'll be happy to help you resolve any issue.