Understanding the Drupal Decoupled Router Module: A Key Tool for Headless CMS

As the demand for modern, JavaScript-powered frontends continues to grow, Drupal developers are increasingly adopting decoupled architectures—often pairing Drupal with frameworks like React, Vue, or Next.js. However, this shift introduces a challenge: How do you resolve internal Drupal URLs (like /node/123) to human-readable paths (like /news/my-article-title) in a decoupled setup?

This is where the Drupal Decoupled Router module comes into play.

What is the Decoupled Router Module?

The Decoupled Router is a contributed Drupal module that exposes a JSON API-compatible endpoint for resolving Drupal's internal routes into path aliases—and vice versa. It’s an essential tool when building decoupled frontends that need to match Drupal’s path alias structure.

Without this module, your frontend would have no easy way of knowing that a piece of content located at /node/123 is also accessible at /about-us (for example).

Why You Need It in a Decoupled Setup

When you’re building a decoupled site:

• The frontend doesn’t have direct access to Drupal’s internal routing system.
• You need to fetch a page like /news/some-article and know what node or entity it corresponds to.
• Or, from a node ID, you might want to display the proper alias path for use in a <Link> component.

The Decoupled Router helps bridge this gap.

Key Features

• ✅ Resolves path aliases to internal routes (e.g., /about → /node/5)
• ✅ Resolves internal routes to aliases (e.g., /node/5 → /about)
• ✅ JSON:API-friendly
• ✅ Works with multilingual sites and custom entities
• ✅ Handles redirects

How It Works

Once installed and enabled, the module exposes an endpoint:

/router/translate-path        

You can use it in two ways:

1. GET /router/translate-path?path=/news/some-article
2. POST /router/translate-path with { "path": "/news/some-article" } in the body

The response provides:

• entity_type
• bundle
• id
• jsonapi resource link
• Translated path information

Example Response

{
  "entity": {
    "id": "123",
    "type": "node",
    "bundle": "article",
    "uuid": "abcd-1234",
    "label": "My Article Title"
  },
  "jsonapi": {
    "individual": "/jsonapi/node/article/123"
  }
}        

This enables your frontend to:

• Fetch the correct JSON:API resource
• Display the correct page
• Match Drupal's URLs for SEO and consistency

Installation

composer require drupal/decoupled_router drush en decoupled_router        

Or enable it via the Drupal admin UI.

Ensure that:

• The JSON:API module is enabled
• Your content uses path aliases (configured via the Pathauto module or manually)

Integration Example (React/Next.js)

When a user navigates to /about-us, your frontend app:

1. Calls /router/translate-path?path=/about-us
2. Gets back the internal route (e.g., node ID and bundle)
3. Calls /jsonapi/node/page/5 to get the actual content
4. Renders the content

This flow ensures full support for:

• Alias-based routing
• SEO-friendly URLs
• Accurate content rendering

Conclusion

The Decoupled Router module is a must-have for any decoupled or headless Drupal setup. It simplifies the bridge between your frontend and backend, enabling friendly URLs, accurate routing, and consistent content delivery.

By using this module, you keep the best of Drupal's content modeling and URL aliasing, while fully embracing modern frontend frameworks.