tessl/npm-rails--ujs

Ruby on Rails unobtrusive scripting adapter that enables modern JavaScript behaviors through HTML5 data attributes

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

AJAX and Remote Requests

Name: tessl/npm-rails--ujs
Author: tessl

Core AJAX functionality for making HTTP requests with Rails conventions, including automatic CSRF protection, response processing, and cross-domain detection.

Capabilities

AJAX Request Function

Makes AJAX requests with Rails conventions including automatic CSRF token handling and response processing.

/**
 * Make AJAX request with Rails conventions
 * @param options - Configuration object for the request
 * @returns XMLHttpRequest instance or false if beforeSend prevents the request
 */
function ajax(options: AjaxOptions): boolean | XMLHttpRequest;

interface AjaxOptions {
  /** Request URL (defaults to current location) */
  url?: string;
  /** HTTP method (GET, POST, PUT, DELETE, etc.) */
  type?: string;
  /** Request data as string or FormData */
  data?: string | FormData;
  /** Expected response type (script, json, html, xml, text, *) */
  dataType?: string;
  /** Accept header value (auto-generated from dataType) */
  accept?: string;
  /** Callback before sending request, return false to cancel */
  beforeSend?: (xhr: XMLHttpRequest, options: AjaxOptions) => boolean;
  /** Success callback for 2xx responses */
  success?: (response: any, statusText: string, xhr: XMLHttpRequest) => void;
  /** Error callback for non-2xx responses */
  error?: (response: any, statusText: string, xhr: XMLHttpRequest) => void;
  /** Completion callback called regardless of success/error */
  complete?: (xhr: XMLHttpRequest, statusText: string) => void;
  /** Whether this is a cross-domain request */
  crossDomain?: boolean;
  /** Include credentials in cross-origin requests */
  withCredentials?: boolean;
}

Usage Examples:

import Rails from "@rails/ujs";

// Basic GET request
Rails.ajax({
  type: "GET",
  url: "/api/users",
  dataType: "json",
  success: (data) => console.log("Users:", data),
  error: (xhr) => console.error("Error:", xhr.status)
});

// POST request with data
Rails.ajax({
  type: "POST",
  url: "/api/users",
  data: "name=John&email=john@example.com",
  success: (response) => console.log("Created:", response)
});

// Request with FormData
const formData = new FormData();
formData.append("file", fileInput.files[0]);
Rails.ajax({
  type: "POST",
  url: "/upload",
  data: formData,
  success: (result) => console.log("Uploaded:", result)
});

Cross-Domain Detection

Determines if a URL represents a cross-domain request by comparing protocols and hosts.

/**
 * Determines if the request is a cross domain request
 * @param url - URL to check for cross-domain
 * @returns True if URL is cross-domain, false if same-origin
 */
function isCrossDomain(url: string): boolean;

Usage Examples:

// Check if URL is cross-domain
if (Rails.isCrossDomain("https://api.external.com/data")) {
  console.log("This is a cross-domain request");
}

// Same-origin check
if (!Rails.isCrossDomain("/api/local")) {
  console.log("This is a same-origin request");
}

Element Href Utility

Gets the href attribute from an element. This function can be overridden to customize link behavior.

/**
 * Get element's href attribute (overridable)
 * @param element - Element to get href from
 * @returns The href value
 */
function href(element: Element): string;

Usage Examples:

const link = document.querySelector('a[data-method="delete"]');
const url = Rails.href(link);

// Custom href behavior (override)
Rails.href = function(element) {
  // Custom logic for determining URL
  return element.getAttribute("data-url") || element.href;
};

Response Processing

The AJAX system automatically processes responses based on Content-Type headers:

JSON responses: Automatically parsed with JSON.parse()
JavaScript responses: Executed as inline scripts with CSP nonce support
XML/HTML/SVG responses: Parsed with DOMParser
Other responses: Returned as-is

Accept Headers

Rails UJS sets appropriate Accept headers based on the dataType option:

const AcceptHeaders = {
  "*": "*/*",
  "text": "text/plain", 
  "html": "text/html",
  "xml": "application/xml, text/xml",
  "json": "application/json, text/javascript",
  "script": "text/javascript, application/javascript, application/ecmascript, application/x-ecmascript"
};

CSRF Integration

All AJAX requests automatically include CSRF protection:

X-CSRF-Token header is added from <meta name="csrf-token">
X-Requested-With: XMLHttpRequest header identifies AJAX requests
Cross-domain requests skip CSRF protection

Data Attribute Integration

Elements with data-remote="true" automatically trigger AJAX requests:

<!-- Link makes AJAX request instead of page navigation -->
<a href="/posts/1" data-remote="true" data-method="delete">Delete</a>

<!-- Form submits via AJAX -->  
<form action="/posts" method="post" data-remote="true">
  <input type="text" name="title">
  <input type="submit" value="Create">
</form>

<!-- Button makes AJAX request -->
<button data-remote="true" data-url="/api/refresh" data-method="post">Refresh</button>

Install with Tessl CLI