Soccor Bros

So You Want to Get Soccor Bros Running

I spent three weeks wrestling with this last winter when my team needed a quick prototype up before a client visit. What follows is the straight version, not the polished blog post. The download sits on their GitHub releases page. Grab the latest zip, extract it somewhere with a short path, then open a terminal there. I learned the hard way that long directory names break the build script on Windows, which cost me an afternoon I didn't have. Run the setup command they document — `npm install` from the root folder. That's it for dependencies. The weird part is the configuration file. You need to create `soccor.config.js` in the root. Start with this skeleton:

module.exports = {
  port: 3000,
  db: 'sqlite:/./data/soccor.db',
  workers: 2
}

Port can be whatever you want. The database defaults to SQLite in development, which is fine until you actually need to handle concurrent requests, then you'll swap it out. Workers controls how many child processes spin up. Keep it at 2 when you're just getting started. After config is in place, run `npm start`. You should see the startup banner and the app listening. Hit localhost on your chosen port and you'll get the default page. If you don't, check your firewall. On Windows, this sometimes gets blocked by default and the error logs are... unhelpful.

How It Actually Works Under the Hood

Soccor Bros is built on a forked architecture pattern. When you start it, the main process reads the config, then spawns worker processes that handle actual request processing. The main process acts as a router. This separation is what makes it flexible, and it's also what trips people up. The routing table lives in `routes/index.js`. Each route maps to a handler file. I spent days confused why my custom endpoints weren't firing until I realized I'd placed them in the wrong directory. The framework doesn't recurse into subdirectories automatically. Every route file needs to be directly in the routes folder or explicitly required. Data persistence is where things get interesting. The default SQLite setup writes to a single file, which works great for development. For production, they support PostgreSQL and MongoDB out of the box. Swap the connection string in config and you're done. No code changes needed.

One thing nobody mentions in the docs: the built-in caching layer. It sits between your handlers and the database. By default it's disabled, but setting `cache: true` in config enables it immediately. Memory usage goes up, query latency drops significantly. On my project it cut average response times from about 200ms to roughly 40ms for read-heavy endpoints.

Common Pitfalls and Things I Wish I'd Known Earlier

The error handling is inconsistent across versions. When something fails, the framework sometimes returns a JSON error and sometimes a full HTML page, depending on which middleware layer threw first. This confused our frontend team because they expected one format and got another. The workaround is wrapping every route handler in a try-catch that explicitly returns JSON errors. Another issue: session management. The default sessions use in-memory storage. That means every worker process has its own session store. If request A hits worker 1 and request B hits worker 2, they don't share session data. For most projects this is fine. For authentication flows that need consistency across requests, you need to switch to Redis or database-backed sessions. Change one line in config. The WebSocket support is decent but quiet. If you're building real-time features, check the examples folder first. There are basic implementations there that save hours of reverse-engineering. I found a working chat room example that adapted to my use case in about twenty minutes after I'd been staring at raw socket code for an afternoon.

When to Use It and When to Move On

Soccor Bros works well for internal tools, dashboards, and prototypes where you need something functional fast. The convention-over-configuration approach means you can have a working API in under an hour if you follow the patterns. For larger applications with complex authentication needs or heavy real-time requirements, you'll hit friction. The routing system doesn't scale cleanly past a certain size, and middleware ordering can become a nightmare. If you need heavy concurrent WebSocket connections, consider pairing it with a dedicated service like Socket.io running separately. The integration isn't built in but the HTTP-to-WS proxy pattern works reliably once you get it configured. For pure REST APIs at scale, there are lighter frameworks that might serve better. But for a team that needs full-stack conventions without thinking about architecture decisions for every new feature, Soccor Bros is solid. I've shipped three projects with it and all three are still running in production.

Download link: [github.com/soccor-bros/soccor/releases](https://github.com/soccor-bros/soccor/releases). Check the README for version-specific notes. The API changed between 2.4 and 3.0 and the migration guide is accurate if you need it.