0
# Rails Active Storage
1

2
Rails Active Storage JavaScript library provides direct file upload functionality to cloud storage services (Amazon S3, Google Cloud Storage, Microsoft Azure Storage) and local disk storage. It enables client-side file uploads without sending files through the Rails application server, improving performance and reducing server load.
3

4
## Package Information
5

6
- **Package Name**: @rails/activestorage
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install @rails/activestorage`
10

11
## Core Imports
12

13
```javascript
14
import { start, DirectUpload, DirectUploadController, DirectUploadsController, dispatchEvent } from "@rails/activestorage";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { start, DirectUpload, DirectUploadController, DirectUploadsController, dispatchEvent } = require("@rails/activestorage");
21
```
22

23
## Basic Usage
24

25
### Automatic Direct Upload Integration
26

27
The simplest way to use Active Storage is through automatic form handling:
28

29
```javascript
30
import { start } from "@rails/activestorage";
31

32
// Initialize automatic form handling for direct uploads
33
start();
34
```
35

36
```html
37
<!-- HTML form with direct upload enabled -->
38
<form>
39
  <input type="file" name="attachments" data-direct-upload-url="/rails/active_storage/direct_uploads" multiple>
40
  <button type="submit">Upload Files</button>
41
</form>
42
```
43

44
### Manual Direct Upload
45

46
For custom upload handling:
47

48
```javascript
49
import { DirectUpload } from "@rails/activestorage";
50

51
const file = document.querySelector("input[type=file]").files[0];
52
const url = "/rails/active_storage/direct_uploads";
53

54
const upload = new DirectUpload(file, url, {
55
  directUploadWillCreateBlobWithXHR(xhr) {
56
    // Called before blob creation request
57
    console.log("Creating blob...");
58
  },
59
  directUploadWillStoreFileWithXHR(xhr) {
60
    // Called before file upload to storage
61
    console.log("Uploading to storage...");
62
  }
63
});
64

65
upload.create((error, blob) => {
66
  if (error) {
67
    console.error("Upload failed:", error);
68
  } else {
69
    console.log("Upload successful:", blob);
70
    // Use blob.signed_id for form submission
71
  }
72
});
73
```
74

75
## Architecture
76

77
Active Storage JavaScript is built around several key components:
78

79
- **UJS Integration**: Automatic form handling via `start()` function that sets up DOM event listeners
80
- **Direct Upload Chain**: Three-stage process of checksum computation, blob record creation, and file storage
81
- **Event System**: Custom DOM events for tracking upload progress and handling errors
82
- **Controller Pattern**: Hierarchical controllers for managing individual files and form-level coordination
83
- **XHR Management**: Raw XMLHttpRequest handling with CSRF token support and custom headers
84

85
The upload process follows this sequence:
86
1. File checksum computation (MD5)
87
2. Blob record creation on Rails backend
88
3. Direct file upload to configured storage service
89
4. Hidden form field population with signed blob ID
90

91
## Capabilities
92

93
### Automatic Upload Integration
94

95
Provides seamless integration with Rails forms through automatic event handling and direct upload coordination.
96

97
```javascript { .api }
98
/**
99
 * Initializes Active Storage automatic direct upload handling
100
 * Sets up DOM event listeners for forms with direct upload file inputs
101
 */
102
function start(): void;
103
```
104

105
[Form Integration](./form-integration.md)
106

107
### Direct Upload Management
108

109
Core functionality for programmatic file uploads with full control over the upload process and event handling.
110

111
```javascript { .api }
112
/**
113
 * Main class for performing direct file uploads to cloud storage
114
 */
115
class DirectUpload {
116
  constructor(file: File, url: string, delegate?: DirectUploadDelegate, customHeaders?: Record<string, string>);
117
  create(callback: (error: string | null, blob?: BlobAttributes) => void): void;
118
  readonly id: number;
119
  readonly file: File;
120
  readonly url: string;
121
}
122

123
interface DirectUploadDelegate {
124
  directUploadWillCreateBlobWithXHR?(xhr: XMLHttpRequest): void;
125
  directUploadWillStoreFileWithXHR?(xhr: XMLHttpRequest): void;
126
}
127

128
interface BlobAttributes {
129
  signed_id: string;
130
  key: string;
131
  filename: string;
132
  content_type: string;
133
  byte_size: number;
134
  checksum: string;
135
}
136
```
137

138
[Direct Upload](./direct-upload.md)
139

140
### Upload Controllers
141

142
Controller classes for managing upload workflows, event dispatching, and coordinating multiple file uploads within forms.
143

144
```javascript { .api }
145
/**
146
 * Controller for managing individual file uploads with event dispatching
147
 */
148
class DirectUploadController {
149
  constructor(input: HTMLInputElement, file: File);
150
  start(callback: (error: string | null) => void): void;
151
  readonly url: string;
152
}
153

154
/**
155
 * Controller for managing multiple file uploads in a form
156
 */
157
class DirectUploadsController {
158
  constructor(form: HTMLFormElement);
159
  start(callback: (error?: string) => void): void;
160
  readonly inputs: HTMLInputElement[];
161
}
162
```
163

164
[Upload Controllers](./upload-controllers.md)
165

166
### Utility Functions
167

168
Helper functions for DOM manipulation, event dispatching, and cross-browser compatibility.
169

170
```javascript { .api }
171
/**
172
 * Dispatches custom DOM events with proper browser compatibility
173
 */
174
function dispatchEvent(element: Element, type: string, eventInit?: {
175
  bubbles?: boolean;
176
  cancelable?: boolean;
177
  detail?: any;
178
}): Event;
179
```
180

181
[Utilities](./utilities.md)
182

183
## Types
184

185
```javascript { .api }
186
interface DirectUploadEventDetail {
187
  id: number;
188
  file: File;
189
  error?: string;
190
  progress?: number;
191
  xhr?: XMLHttpRequest;
192
}
193

194
interface DirectUploadEvents {
195
  "direct-uploads:start": { detail: {} };
196
  "direct-uploads:end": { detail: {} };
197
  "direct-upload:initialize": { detail: DirectUploadEventDetail };
198
  "direct-upload:start": { detail: DirectUploadEventDetail };
199
  "direct-upload:before-blob-request": { detail: DirectUploadEventDetail };
200
  "direct-upload:before-storage-request": { detail: DirectUploadEventDetail };
201
  "direct-upload:progress": { detail: DirectUploadEventDetail };
202
  "direct-upload:error": { detail: DirectUploadEventDetail };
203
  "direct-upload:end": { detail: DirectUploadEventDetail };
204
}
205
```