Stellify Bundler Service

A lightweight Node.js service that bundles Vue 3 Single File Components (SFCs) and JavaScript files using esbuild. This service is required to publish Vue/JS bundles from Stellify.

Why is this needed?

Stellify is hosted on Laravel Cloud, which doesn't support Node.js. To bundle Vue SFCs and JavaScript modules, you need to run this service separately and connect it to your Stellify account.

Quick Start

Option 1: Railway (Recommended)

Railway offers a simple deployment with a generous free tier.

1. Fork this repository to your GitHub account

2. Create a Railway account at railway.app

3. Create a new project:

   • Click "New Project"
   • Select "Deploy from GitHub repo"
   • Choose your forked repository

4. Deploy:

   • Railway will automatically detect the Node.js app
   • Wait for the deployment to complete
   • Click on your service and go to "Settings" > "Networking"
   • Click "Generate Domain" to get your public URL

5. Copy your URL:

   • Your bundler URL will be something like: https://your-app-name.up.railway.app/bundle

6. Configure Stellify:

   • In Stellify, go to Settings > Integrations
   • Enter your bundler URL

Railway Pricing: Free tier includes 500 hours/month. Paid plans start at $5/month for unlimited usage.

Option 2: Render

Render offers free web services with some limitations.

1. Fork this repository to your GitHub account

2. Create a Render account at render.com

3. Create a new Web Service:

   • Click "New" > "Web Service"
   • Connect your GitHub account
   • Select your forked repository

4. Configure the service:

   • Name: stellify-bundler (or your choice)
   • Runtime: Node
   • Build Command: npm install
   • Start Command: npm start

5. Deploy and copy your URL (e.g., https://stellify-bundler.onrender.com/bundle)

Render Pricing: Free tier available (spins down after inactivity, 750 hours/month). Paid plans from $7/month.

Option 3: Fly.io

Fly.io offers edge deployment with a free tier.

1. Install the Fly CLI:

   curl -L https://fly.io/install.sh | sh

2. Login and launch:

   fly auth login
   fly launch

3. Deploy:

   fly deploy

4. Get your URL:

   fly status

   Your URL will be https://your-app-name.fly.dev/bundle

Fly.io Pricing: Free tier includes 3 shared VMs. Paid usage is pay-as-you-go.

Option 4: Self-Hosted (VPS/Docker)

For full control, run on your own server.

Using Node.js directly:

git clone https://github.com/YOUR_USERNAME/stellify-bundler-service.git
cd stellify-bundler-service
npm install
PORT=3000 npm start

Using Docker:

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

docker build -t stellify-bundler .
docker run -p 3000:3000 stellify-bundler

Local Development Mode (Real-time Preview)

For real-time development with instant preview, run the bundler locally on your machine.

Setup

git clone https://github.com/YOUR_USERNAME/stellify-bundler-service.git
cd stellify-bundler-service
npm install
npm start

You'll see:

Bundler service running on port 3001
  HTTP:      http://localhost:3001/bundle
  WebSocket: ws://localhost:3001/ws
  Health:    http://localhost:3001/health

Note: The default port is 3001 to avoid conflicts with Laravel's development server (port 3000) and Vite (port 5173).

Configure Stellify for Local Development

1. In Stellify, go to Settings > Integrations
2. Enable "Local Development Mode"
3. The bundler URL will automatically use http://localhost:3001

How It Works

When in local dev mode, Stellify connects to your local bundler via WebSocket:

1. You edit code in Stellify
2. Changes are sent to ws://localhost:3001/ws instantly
3. Local bundler compiles in ~50ms (no minification for speed)
4. Preview updates in real-time

WebSocket Protocol

Connect to ws://localhost:3001/ws to receive a session:

{ "type": "connected", "sessionId": "session-xxx" }

Send bundle requests:

{
  "type": "bundle",
  "requestId": "unique-id",
  "files": [...],
  "entryPoint": "App.vue"
}

Receive results:

{
  "type": "bundle-result",
  "requestId": "unique-id",
  "success": true,
  "js": "/* bundled code */",
  "size": 12345,
  "buildTime": 48
}

API Reference

POST /bundle

Bundles multiple files into a single JavaScript output. Used for production publishing.

Request Body:

{
  "files": [
    {
      "path": "App.vue",
      "content": "<template>...</template><script setup>...</script>"
    },
    {
      "path": "utils.js",
      "content": "export const helper = () => {}"
    }
  ],
  "entryPoint": "App.vue",
  "filename": "my-bundle"
}

Response:

{
  "success": true,
  "js": "/* minified bundle */",
  "size": 12345,
  "filesProcessed": 2
}

GET /health

Health check endpoint.

Response:

{
  "status": "ok",
  "websocket": true,
  "activeSessions": 0
}

WebSocket /ws

Real-time bundling for development. See Local Development Mode for details.

Configuration

| Environment Variable | Default | Description | |---------------------|---------|-------------| | PORT | 3001 | Port the service listens on |

Supported File Types

• .vue - Vue 3 Single File Components (with <script setup> support)
• .js - JavaScript ES modules

Troubleshooting

"Bundler request failed" in Stellify

1. Check your bundler URL is correct (should end with /bundle)
2. Verify the service is running: visit https://your-url/health
3. Check the service logs for errors

Service is slow or timing out

• The free tier on some platforms spins down after inactivity
• First request after idle may take 10-30 seconds
• Consider upgrading to a paid tier for consistent performance

CORS errors

The service includes CORS headers by default. If you're still seeing CORS errors, ensure you're using the full URL including https://.

Security Notes

• This service processes code you send to it - only connect to bundlers you control
• Consider adding authentication if exposing to the public internet
• Review the code before deploying to understand what it does

License

MIT