Skip to main content

Auto-Discovery

In most backend frameworks, adding a new endpoint means two steps: write the code for it, and then go tell the framework it exists, usually by adding a line to some central "router" file. Forget the second step, and your new endpoint silently doesn't work.

RapidREST only has the first step. There is no file where you register your routes, your data models, or your background jobs. You write a class, export it from a file somewhere under src/, and it's found and wired up automatically the next time the server starts. This is called auto-discovery, and it's handled by a piece of the framework called the ClassLoader.

How it actually finds your code​

When your server starts, the ClassLoader walks through every file in your source folder, opens each one, and looks for anything it exports. If a file exports a class, that class gets registered. That's the entire rule. It doesn't matter what the file is named, what folder it's in, or what the class does.

src/
├── routes/
│   └── PetRoute.ts     ← exports a class → found → registered
├── models/
│   └── Pet.ts          ← exports a class → found → registered
└── services/
    └── PetService.ts   ← just a plain class, no decorators → found anyway

Notice that last one: PetService isn't a route or a model, it's just a regular class with some business logic in it. It still gets picked up, because discovery never asks "does this look like a route?" It only asks "is this an exported class under src/?" That plain class becomes available for other classes to use (see Dependency Injection), with nothing extra required from you.

Each discovered class also gets a name the framework can refer to it by, built from its file path: a class in src/routes/PetRoute.ts is known internally as routes.PetRoute. You won't usually need to know or type this name yourself, most of the time you refer to a class directly, but it's what's happening under the hood when the framework needs to look something up by string instead.

What this buys you​

  • Adding a feature is just adding a file. Write a new route class with a @Route decorator on it (see Decorators & Aspects), save it under src/routes/, restart, and it's live. There's no router file to remember to update, so there's no way to forget to update it.
  • You can organize your code however you want. Folder names like routes/ and models/ in the examples above are a convention this project happens to use, not a rule the framework enforces. Discovery doesn't care about folder structure or file naming at all.
  • Plain helper classes are just as easy to reuse as framework classes. A PetService with no decorators on it at all is exactly as discoverable, and exactly as easy for other code to ask for, as a fully decorated route or model.

Telling it what to skip​

Not every file under src/ is meant to be a class the framework should manage. Your server's own startup file and your config file, for example, aren't things you want treated as a route or a model. Tell the ClassLoader to ignore them by matching their filenames with a regular expression:

conf.defaults({
  class_loader: {
    ignore: [/server\..*/, /config\..*/],
  },
});

A freshly generated project already comes with this set up correctly, you'll only need to touch it if you add your own files that shouldn't be scanned.

Why this is worth understanding early

Routing, data models, background jobs, and event listeners are all powered by this exact same mechanism. Once "the framework finds classes by scanning src/ for exports" clicks, a lot of what looks like magic in the rest of these docs stops looking like magic.