Bun on Falix

Reach for Bun when you want TypeScript without a build step. Bun is a fast JavaScript runtime that runs .ts files directly — no tsc, no dist/ folder, no compile stage to babysit. The Bun application on Falix behaves a lot like the Node.js one, with the same auto-install convenience, plus native TypeScript on top.

The three rules

1. Your code starts from your main file. When you press Start, Falix runs bun run <main file>. The default is index.js, set by the Main file variable on the Settings page — and because Bun runs TypeScript natively, you can point that variable straight at an index.ts and it just works. (The Hono API template on this page is built around an index.ts.)

2. Dependencies install themselves. If a package.json exists, bun install runs automatically every time the server starts, before your code. You edit package.json, restart, and watch the install happen in the console — no commands to type.

3. Your public port is SERVER_PORT. Bun's built-in server reads the port from the environment and binds 0.0.0.0. The cleanest way is the default-export pattern:

   export default {
     port: Number(process.env.SERVER_PORT) || 8080,
     hostname: "0.0.0.0",
     fetch(req: Request) {
       return new Response("Hello from Bun on Falix!");
     },
   };

   Bun starts a server from that object automatically — no Bun.serve(...) call needed. Binding 0.0.0.0 (not localhost) on SERVER_PORT is what makes your app reachable from outside; see Your first web app.

Try it: a Hono API

Deploy the Bun + Hono API template from this page (it only overwrites files with the same names). Hono is a tiny, fast web framework that fits Bun perfectly. Press Start, and the console shows Bun booting and your API listening on the server port. Open your server's address (Network page) in a browser to hit the endpoint. Then edit index.ts in the File Manager, restart, and refresh — that edit-restart-check loop is Bun development on Falix.

Adding packages

Bun uses the same package ecosystem as Node, so adding libraries works the same way. Open the Packages page in your server menu, type the package name into the Install package panel, and press Install. The job runs under Tasks, your package.json is updated for you, and after a restart the import works. The page also lists your current dependencies, flags outdated ones, and warns about known vulnerabilities. If your app ever crashes with a missing-module error, the console offers to open Packages or install it in one click.

A different file, several apps, and reinstalls

Your entry point is the Main file variable — point it at any .js or .ts file in your project. To run a genuinely separate app, though — a second bot, another API — don't cram it into the same folder. Give it its own Instance: an isolated application, files, and startup on the same server, switched like a save slot.

🎯 Good to know: node_modules isn't yours to keep. A reinstall — or switching the server to a different application — can wipe your files, and node_modules goes with them. You don't rebuild it by hand: bun install runs on the next start and restores it. Guard your own source and data instead (managed databases are the safe home for data).

Bun or Node?

Both applications auto-install from package.json and share the Packages page, so you won't feel lost switching between them. Pick Bun when you want to write TypeScript with zero build setup, or want Bun's fast startup and built-in tooling. Pick Node.js when you need the widest possible ecosystem compatibility or you're following a tutorial written specifically for Node.

🎯 Good to know: For TypeScript in particular, Bun is the shortcut: on the Node application a bare .ts entry file won't run, but on Bun it just works.

When things go wrong

• Missing-module error on start — the package isn't in package.json, or the bun install above it in the console failed. Scroll up and read the install output first, then use the Packages page.
• Server starts, then immediately stops — your code finished and exited. That's not a crash: an HTTP server or bot stays alive because it keeps a listener open; a script that just runs and returns is done. See My app won't start.
• Nothing reachable in the browser — check the port and bind address: I can't reach my app.
• Killed out of nowhere under load — likely memory: Out of memory.

Next steps

• Build your first web app
• Node.js on Falix
• Deploy your code with Git