New to Rust? Grab our free Rust for Beginners eBook Get it free →
Meteor Routing with Iron Router

In a Meteor app, a URL can open a page, and it can also reach a server handler. Iron Router connects URL paths to client templates or server-side request handlers.
This tutorial shows how to add a route for a template and set up a server endpoint.
TL;DR
Iron Router maps Meteor URLs to client templates or server handlers, and route parameters let one route serve many records.
- Install it with meteor add iron:router.
- Use this.render() for a client template.
- Read dynamic path values from this.params.
- Set where: ‘server’ for an HTTP endpoint.
What is Iron Router in Meteor?
Iron Router is a Meteor package that dispatches URLs to client-side templates or server-side request handlers. A client route can change the page view without requesting a whole new HTML document. A server route can respond directly to an HTTP request.
A route has a path, an action, and optionally a name, template, data context, layout, or subscription rule. Route actions run with a controller as this, which provides methods such as render() and values such as params. This is the core distinction from writing a URL switch yourself: the router also connects paths to Meteor templates and reactive data.
The package guide includes a quick start that demonstrates the installation command and a basic route declaration.

This is a documentation view, not output from a running Meteor app. The route samples below follow the official guide.
How to add Iron Router routes in Meteor
Create the package dependency, add a template, then connect its URL to the template. I favor an explicit render call in a first example because it makes the route-to-view relationship visible.
Step 1: Add the package
From the project root, add Iron Router without deleting generated starter files. Inspect the project first and remove only files you understand and no longer need.
meteor add iron:router
Meteor records the package in the project so it is available to the app. The official guide uses the same package identifier, iron:router.
Step 2: Create a route for a template
Place a route in client-side JavaScript and give the page a template with the same name you pass to render. This example handles the home URL.
Router.route('/', function () {
this.render('Home');
});
Define the matching Blaze template in an HTML file:
<template name="Home">
<h1>Welcome</h1>
</template>
When the browser reaches /, the action renders Home. A route without an explicit action can use template lookup based on its name, but explicit rendering is less surprising while learning.
Step 3: Capture a route parameter
Use a colon-prefixed name in the path when a URL contains a changing value. The matched string is available through this.params.
Router.route('/posts/:_id', function () {
const postId = this.params._id;
this.render('Post', {
data: function () {
return Posts.findOne({ _id: postId });
}
});
});
A request for /posts/42 gives the route the string value “42” as this.params._id. Treat URL values as input, not as trusted database records. If IDs have a known format, validate that format and render a not-found state when the record lookup returns no document.
Step 4: Reuse a layout and wait for data
A layout holds shared regions such as navigation and a content area. Put a yield in the layout, then configure the router to use it. A route can wait for a subscription before its action renders.
<template name="ApplicationLayout">
<header>Site navigation</header>
{{> yield}}
</template>
Router.configure({
layoutTemplate: 'ApplicationLayout',
loadingTemplate: 'Loading'
});
Router.route('/posts/:_id', {
waitOn: function () {
return Meteor.subscribe('post', this.params._id);
},
action: function () {
this.render('Post');
}
});
The server must publish the data and the client must subscribe to it for this setup to work. A loading template handles the interval before the subscription is ready. It does not replace authorization checks in the publication.
Step 5: Add a server endpoint
A server route can answer an HTTP request without rendering a client template. Set the route’s location explicitly and end the response.
Router.route('/health', function () {
this.response.setHeader('Content-Type', 'text/plain');
this.response.end('ok');
}, { where: 'server' });
This handler returns plain text at /health. For a JSON API, serialize a deliberate response shape and set the matching content type. Avoid returning collection contents without an access-control decision.
Route parameters, links, and missing data
Path parameters identify a resource, query parameters filter or modify a request, and hashes identify a location within a page. Iron Router exposes these values on the route parameters object, so read the property that matches the URL component you need.
| URL part | Example | Route access |
|---|---|---|
| Path parameter | /posts/42 | this.params._id |
| Query string | ?sort=recent | this.params.query.sort |
| Hash fragment | #comments | this.params.hash |
For navigation, named routes reduce repeated path strings. The guide documents helpers such as pathFor for generating a route path from a name and data. If a route has parameters, provide the corresponding values when generating its URL.
<a href="{{pathFor route='post.show' data=post}}">Read post</a>
When a lookup returns no document, handle that state separately from an unmatched URL. Iron Router’s dataNotFound plugin can render a configured not-found template when route data is falsey. A catch-all route handles paths that do not match a declared route, and should be placed after specific routes.
Common Iron Router mistakes and fixes
Routing bugs usually come from placing a route in the wrong execution context, mismatching a template name, or assuming data has arrived before a subscription is ready. Check the URL, route declaration, rendered template name, and data state in that order.
| Symptom | Likely cause | Check |
|---|---|---|
| URL changes but view does not | Template name or render action does not match | Confirm the template name and call to this.render() |
| Parameter is undefined | Path token differs from property read in the action | Compare :_id with this.params._id |
| Data is empty on first render | Subscription has not completed or publication returns no record | Wait for readiness and inspect the publication |
| Server endpoint renders app HTML | Route was declared as a client route | Set where: ‘server’ and return a response |
| Specific route never matches | A broad catch-all was registered first | Move the catch-all after named routes |
Iron Router hooks can run before an action. When a hook blocks the next route action, call this.next() in the path that should continue. A login check should protect the relevant data on the server as well, since hiding a client view alone is not an authorization boundary.
The older example that chains .get(), .post(), .put(), and .delete() should not be copied as a complete CRUD service without reviewing current Meteor and package behavior, request parsing, authentication, validation, and error responses. The project README shows server routes with chained HTTP methods, but the application still owns those security and data rules.
A route’s path and its rendered template are separate choices. For a route called items.show, you can define an explicit path such as /items/:_id and render a differently named template. Explicit names help when the page has a domain meaning that differs from its path.
The router can infer a template name from a route name. That naming convention may be less clear to someone reading the code later.
Routes are evaluated against the requested location. A route parameter matches one path segment. It does not validate that the segment is a database ID or that the current user may see the record.
Use a lookup and authorization rule in the appropriate server-side code. If the item is absent, return a deliberate not-found view instead of allowing a missing value to become an obscure template error.
Query parameters are useful for optional view state such as sorting or search terms. They do not change the route’s identity segment. Read them from this.params.query and validate values before use.
A query string is user-controlled input. Do not interpolate arbitrary values into HTML or build database selectors from them without checking allowed fields.
A hash fragment is handled by the browser for in-page navigation, and Iron Router exposes it through route parameters when application code needs it. I would keep ordinary anchor navigation for a link to a section. Use reactive parameter access only when the application must respond to changes in the fragment without a route transition.
Route data, loading states, and layouts
A layout prevents every page from repeating shared markup, and route data can make a matched record available to the template. The choice between a single route action and route options depends on how much behavior the page needs: a short static page can render directly, while a data-backed page benefits from keeping its data and subscription rules close to the route.
In a layout template, the unnamed {{> yield}} marks where the route’s main view appears. Named yields allow additional regions such as a sidebar or footer. A route can render a template into a named region.
Route options can map a region to a template. Keep the layout focused on shared structure. Route-specific page content belongs in the view rendered into its yield.
Reactive data changes can cause route computation to recur. A view can derive from current reactive state.
Route actions should not perform unrelated one-time side effects. Use lifecycle hooks for work tied to a route transition. Check which hooks run on entry or after reactive changes.
Subscription readiness and record existence are different states. A ready subscription can still contain no matching document. An unready subscription means the client has not received the publication’s data yet.
Present a loading state while data is pending and a not-found state when the query has no record. This avoids showing a temporary network wait as a missing page.
| Route state | What it means | View response |
|---|---|---|
| Subscription not ready | Published data has not arrived at the client | Render a loading template |
| Subscription ready, record found | The route’s data function returns the record | Render the detail template |
| Subscription ready, record absent | No document matches the requested identifier | Render a not-found state |
| No route matches | The path is outside declared routes | Use an intentional fallback or server 404 response |
Router.configure({ loadingTemplate: 'Loading' });
Choose waitOn when the route should wait for a subscription before its action proceeds and the loading behavior is appropriate. The guide also describes a subscriptions option when you want subscription readiness without the same automatic loading hook behavior. Pick one based on the desired rendering sequence, then make the loading and empty-data states explicit in the UI.
Naming routes and generating links
A named route lets navigation code refer to a route by purpose instead of duplicating its URL. That is useful when a path includes a parameter or may change while its meaning stays the same. Give the route a stable name, then use a route helper to construct the path from the required data.
Router.route('/posts/:_id', function () {
this.render('Post');
}, {
name: 'post.show'
});
In a template, pathFor can generate the anchor target from the route name and the current data context. This reduces hard-coded paths, but the helper still needs the parameter required by the path. If the data context is missing the ID, check the context passed into the template before debugging the router itself.
{{#with post}}
<a href="{{pathFor route='post.show'}}">Open post</a>
{{/with}}
Use a generated path for links inside the app. Use a full URL helper when a complete absolute URL is needed outside the current page, such as when constructing a link for another system. Avoid building the same path with string concatenation in several templates because route changes then require several unrelated edits.
When to use a server route
A server route is appropriate when a request needs a server response such as plain text, a file, or an endpoint for an external integration. A client route is the choice for rendering the Meteor application’s interactive view. This distinction matters because server handlers receive HTTP request and response objects, while a client route renders a template in the browser.
| Use a client route | Render an interactive Meteor template |
|---|---|
| Use a server route | Return an HTTP response to a request |
The official guide shows a server route using where: ‘server’ and ending the response. A route can also declare handlers for HTTP verbs.
Before exposing a write endpoint, decide how the caller is authenticated. Validate accepted input fields and define the errors the endpoint returns. Routing alone does not supply those protections.
For a small health check, return a fixed response and avoid database access. For an endpoint that reads application data, return only fields the caller may receive.
For write routes, validate the body and enforce permission checks on the server. A hidden client button does not protect an endpoint.
Set an accurate content type and ensure every intended path ends the response. Otherwise, the request may wait indefinitely. Choose a response format consistently for success and failure.
Keep API routes separate from page routes in the source tree. A prefix such as /api can make the execution context visible during code review. This naming choice does not replace endpoint authentication or a check for overlapping client and server routes.
Conclusion
Iron Router connects Meteor paths to views and HTTP handlers. Begin with an explicit client route, add parameters and a shared layout as needed, then use server routes only when the request needs an HTTP response.
For background on Meteor’s application model, see the Meteor.js framework introduction. To compare routing in a separate Node.js framework, see the Express Router tutorial. The Iron Router guide covers route options, layouts, subscriptions, hooks, and server routing.
FAQ
These answers cover the basic package and route choices.
How do I use Iron Router in Meteor?
Install it with meteor add iron:router, declare a route with Router.route(), and render a Meteor template from the route action.
Can Iron Router handle server-side routes?
Yes. Declare a route with the where: ‘server’ option and use the request and response objects to handle the HTTP request.
How do I read a route parameter?
Declare a named path segment such as :_id and read its value from this.params._id inside the route action.




