Rails Request.JS

Request.JS automatically processes Turbo Stream responses. To ensure this works, you must ensure the window.Turbo global variable is set. If you are using @hotwired/turbo-rails version 7.0.0-beta.6 or later, this is handled automatically. Otherwise, set it manually:

import { Turbo } from "@hotwired/turbo-rails"
window.Turbo = Turbo

Request.JS also uses Turbo's fetch to include the X-Turbo-Request-ID header.

Depending on your Rails asset pipeline, use one of the following methods to install Rails Request.JS:

Asset Pipeline

Install the requestjs-rails gem and follow the instructions provided by that gem.

Webpacker/Esbuild

Use npm or yarn to add the package to your project.

### npm
```bash
npm i @rails/request.js

yarn

yarn add @rails/request.js

You can make requests using the FetchRequest class or by using shorthand methods for common HTTP verbs like get, post, put, patch, and destroy.

Using FetchRequest

Instantiate FetchRequest with the method, URL, and options, then call .perform().

Using Shorthand Methods

Import the shorthand functions directly for a more concise syntax.

import { FetchRequest, get, post, put, patch, destroy } from '@rails/request.js'

// Using FetchRequest
async function useClass() {
  const request = new FetchRequest('post', 'localhost:3000/my_endpoint', { body: JSON.stringify({ name: 'Request.JS' }) })
  const response = await request.perform()
}

// Using shorthand
async function useShorthand() {
  const response = await post('localhost:3000/my_endpoint', { body: JSON.stringify({ name: 'Request.JS' }) })
}

You can use RequestInterceptor to intercept requests and add headers, such as a Bearer token, before the request is sent. This is useful for asynchronous token retrieval.

import { RequestInterceptor } from '@rails/request.js'

// Set interceptor
RequestInterceptor.register(async (request) => {
  const token = await getSessionToken(window.app)
  request.addHeader('Authorization', `Bearer ${token}`)
})

// Reset interceptor
RequestInterceptor.reset()

The response object returned by perform() or shorthand methods provides several properties and methods to inspect the result:

• ok: Boolean indicating if the response was successful.
• statusCode: The HTTP status code.
• unauthenticated: Boolean indicating if the response has a 401 status code.
• authenticationURL: The value from the WWW-Authenticate header.
• contentType: The response's content-type.
• headers: The response headers.
• json: A promise that resolves to the JSON body. Rejects if the content-type is not application/json.
• html: A promise that resolves to the HTML body. Rejects if the content-type is not html.

The core classes for managing the request lifecycle are exported from the main entrypoint:

• FetchRequest: The primary class used to construct and configure an HTTP request.
• FetchResponse: A wrapper around the native Fetch API response, providing enhanced utility methods.
• RequestInterceptor: A class used to define logic that intercepts and modifies requests (e.g., for adding authentication headers).

import { FetchRequest, FetchResponse, RequestInterceptor } from '@rails/request.js';

The responseKind option determines the Accept header sent with the request. This is useful for telling the Rails backend what format you expect in return.

Supported values:

• 'html': Sets Accept to text/html, application/xhtml+xml (default).
• 'turbo-stream': Sets Accept to text/vnd.turbo-stream.html, text/html, application/xhtml+xml.
• 'json': Sets Accept to application/json, application/vnd.api+json.
• 'script': Sets Accept to text/javascript, application/javascript.
• Any other value defaults to */*.

const request = new FetchRequest('GET', '/api/data', {
  responseKind: 'json'
})

The RequestInterceptor class allows you to register a single global interceptor that can be used to extend or modify requests. You can register an interceptor using RequestInterceptor.register(interceptor), retrieve the current interceptor with RequestInterceptor.get(), or clear it using RequestInterceptor.reset().

import { RequestInterceptor }

// Register an interceptor
RequestInterceptor.register(myInterceptor);

// Retrieve the registered interceptor
const interceptor = RequestInterceptor.get();

// Remove the interceptor
RequestInterceptor.reset();

You can use the following boolean getters to check the Content-Type of a FetchResponse:

• isTurboStream: Returns true if the content type is text/vnd.turbo-stream.html.
• isScript: Returns true if the content type contains javascript (e.g., application/javascript or text/ecmascript).
• contentType: Returns the base MIME type (e.g., application/json) with parameters stripped away.

The FetchResponse class provides high-level getters to inspect the status of a response. You can check if a request was successful, if it was redirected, or if it failed due to authentication or validation errors.

Key properties:

• statusCode: Returns the HTTP status code.
• ok: Returns true if the status is in the range 200-299.
• redirected: Returns true if the response was the result of a redirect.
• unauthenticated: Returns true if the status code is 401.
• unprocessableEntity: Returns true if the status code is 422.
• authenticationURL: Returns the value of the WWW-Authenticate header, useful for identifying where to redirect for authentication.