# Add File Uploads to an AdonisJS App

Yes. An agent adds an avatar upload to your AdonisJS app with Drive, a validated multipart form, a settings page, functional tests on a fake disk, and a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-file-uploads/adonisjs/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the app and its conventions before it adds a route. In the `hypermedia` starter kit from adonisjs/starter-kits, `package.json` depends on `@adonisjs/core` `^7.5.2`, `@adonisjs/lucid` `^22.4.2` with `better-sqlite3`, `@adonisjs/auth`, `@adonisjs/session`, `@adonisjs/shield`, `@adonisjs/static`, `@adonisjs/vite`, `@vinejs/vine` and `edge.js`, and its `imports` map `#controllers/*`, `#validators/*`, `#models/*` and `#generated/*` to their directories. `adonisrc.ts` registers an `indexEntities()` hook, which is why `start/routes.ts` points at controllers through the generated `#generated/controllers` registry, and declares `unit`, `functional` and `browser` test suites, though `tests/` holds only `bootstrap.ts`. `app/models/user.ts` extends the generated `UserSchema` in `database/schema.ts`, a file written by `node ace migration:run` from the single migration that creates `users` with `full_name`, `email` and `password`. `config/bodyparser.ts` already processes `multipart/form-data` automatically with a `20mb` limit. `resources/views/components/avatar.edge` renders an `img` when given `src` and initials otherwise, `resources/views/components/layouts/settings.edge` has an empty `items` list with a comment showing how to add a page, and `.gitignore` ignores `tmp/*`.

Storage goes through `@adonisjs/drive`, whose current release lists `@adonisjs/core` `^7.0.0` as a peer. `node ace add @adonisjs/drive` installs it, registers its provider in `adonisrc.ts`, writes `config/drive.ts` and adds `DRIVE_DISK=fs` to `.env` and `.env.example`; the agent sets the `fs` service to `location: app.makePath('storage')`, `serveFiles: true`, `routeBasePath: '/uploads'` and `visibility: 'public'`, adds `storage` to `.gitignore`, and validates the new variable in `start/env.ts`. A migration adds a nullable `avatar_key` string column to `users`, and running it regenerates `database/schema.ts` so `UserSchema` gains the column without a hand edit.

The feature is a profile page in the settings area. `app/validators/profile.ts` defines `avatarValidator` with `vine.file({ size: '2mb', extnames: ['jpg', 'jpeg', 'png', 'webp'] })`, below the body parser's own limit so the validator's message is what a user sees. A `ProfileController` with `show` and `updateAvatar` is created with `node ace make:controller` so the registry picks it up; `updateAvatar` validates the request, builds a key from `cuid()` in `@adonisjs/core/helpers` and the file's `extname`, calls `avatar.moveToDisk(key)`, deletes the previous key from the disk when there was one, saves the key on the user and redirects back with a flash message. `start/routes.ts` gets `GET /settings/profile` and `POST /settings/profile/avatar` inside the existing `middleware.auth()` group, the settings layout's `items` gets `{ label: 'Profile', route: 'settings.profile', icon: 'lucide:user' }` as its comment suggests, and `pages/settings/profile.edge` renders the `avatar` component with `src` set through the `driveUrl` helper when a key exists and `initials` from the model's getter otherwise, above a form with `enctype="multipart/form-data"` and the kit's `field`, `input` and `button` components.

Tests use the functional suite. The agent adds `@japa/api-client` with the `authApiClient` and `sessionApiClient` plugins beside the browser client in `tests/bootstrap.ts`, writes `tests/functional/profile.spec.ts` that signs a user in with `loginAs`, posts a small PNG from `tests/fixtures` with the client's `file` helper, and asserts the redirect, the `avatar_key` on the reloaded user and that the key exists on the disk; a second test posts a text file and asserts the validation error, and a third posts without a session and asserts the guest redirect. Every test runs under `using fakeDisk = drive.fake()` so nothing touches `storage/`. It runs `node ace migration:run`, `npm run lint`, `npm run typecheck` and `node ace test functional` in its sandbox, and opens the pull request when all three pass.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add file uploads to this AdonisJS app as an avatar on a profile settings page and open a pull request. Read package.json, adonisrc.ts, start/routes.ts, start/kernel.ts, start/env.ts, config/bodyparser.ts, app/models/user.ts, database/schema.ts, database/migrations, app/validators/user.ts, app/controllers, resources/views/components/avatar.edge, resources/views/components/layouts/settings.edge, tests/bootstrap.ts and .gitignore first. Install @adonisjs/drive with node ace add, configure the fs disk under storage with serveFiles and an /uploads base path, validate DRIVE_DISK in start/env.ts and ignore storage in git. Add a migration for a nullable avatar_key on users and run it so the generated schema updates. Add a profile validator with vine.file limited to 2mb and image extensions, a ProfileController made with node ace make:controller whose updateAvatar validates, moves the file to the disk under a cuid key, deletes the old key, saves the user and redirects with a flash message, and routes under the auth group. Add the Profile entry to the settings layout and a profile page using the avatar component and driveUrl. Add @japa/api-client to tests/bootstrap.ts and functional tests on drive.fake() for a valid image, a rejected text file and a guest. Run node ace migration:run, npm run lint, npm run typecheck and node ace test until they pass, then open a pull request listing the routes, the config and what each test proves.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request adds `config/drive.ts`, the migration, `app/controllers/profile_controller.ts`, `app/validators/profile.ts`, `resources/views/pages/settings/profile.edge`, `tests/functional/profile.spec.ts` and a small fixture image, and changes `adonisrc.ts`, `package.json`, `pnpm-lock.yaml`, `.env.example`, `start/env.ts`, `start/routes.ts`, `database/schema.ts`, `.gitignore` and the settings layout. Its description lists the two routes, shows the `fs` disk configuration, and quotes the lint, typecheck and test output from the sandbox.

It explains the choices a reviewer will ask about: the key is a `cuid` with the original extension rather than the client's file name, so a name is never a path; the old file is deleted after the new one is saved, so a failed upload leaves the previous avatar in place; and the public `fs` disk serves files from `/uploads` through the app, which the description says to swap for `s3` or `gcs` in `config/drive.ts` when the app runs on more than one host.

Before merging, a reviewer decides whether a bucket disk should be configured now, whether the `2mb` limit and the extension list match the product, and whether the `avatar` component should get a `loading="lazy"` attribute or a fixed size now that it renders real images.

## Run it on every Linear issue labelled uploads

An automation on the Project with a `linear` trigger on `linear.issue.labeled`, `uploads` in `config.labels`, and the prompt "this issue names a form or model that should accept a file; add a validated upload field on the existing disk, store the key on the model, extend the functional tests on a fake disk, and open a pull request" starts one run per labelled issue once Drive is configured. The trigger adds the issue after the prompt and fills in nothing else, so an issue about attachments on a support ticket gets a key column on that model and a field on that form.

A team with several AdonisJS apps sends this body once per repository from its own server, each `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own kit: the `api` kit gets a JSON route and an `api-client` test instead of a page, and an app that already has Drive gets only the migration, the controller and the tests.

## Why run it on Rush?

An upload touches the body parser, a disk, a migration, a generated schema file, a validator, a view and the test harness, and each has a convention in this kit: controllers are registered through a generated index, the schema file is written by the migration command, settings pages are listed in a layout. The agent follows each one and proves the whole path with functional tests that post a real file in its sandbox, where it can run the migration against the kit's SQLite database and a fake disk without touching anyone's storage.

The migration output, the lint and typecheck runs and the test results stay with the run, so a reviewer sees the form accept an image and refuse a text file without starting the app. A team with several AdonisJS services sends the same request to all of them at once and reads one pull request per app.

## Frequently asked questions

### Where do the files go?

On the `fs` disk under `storage/`, which is ignored by git and served by the app at `/uploads/<key>` because `serveFiles` is on. `config/drive.ts` is where that becomes `s3` or `gcs`; the controller calls `moveToDisk` and `driveUrl` and does not care which.

### Why is the limit in the validator when the body parser has one?

The body parser's `20mb` limit protects the server and answers with a bare error. The validator's `2mb` limit is checked per field and reports through the same flash messages the signup form uses, so the user sees which file was too large and why. The validator limit must stay below the parser's or it never gets to run.

### Does it edit the generated schema file by hand?

No. `database/schema.ts` says it is regenerated by `node ace migration:run`, so the agent writes a migration for `avatar_key` and runs it; the `UserSchema` class gains the column from the migration, and the `User` model needs no change.

### How do the tests avoid writing to storage?

Each test runs under `using fakeDisk = drive.fake()`, which points the disk at a temporary directory for the test's lifetime and restores it after. The assertions check the key on the user and `fakeDisk.assertExists` for the file, so they prove the write happened without leaving a file behind.

## More AdonisJS jobs

- [Set Up GitHub Actions CI for an AdonisJS App](https://getrush.ai/run/add-github-actions-ci/adonisjs/)
- [Add Google Login to an AdonisJS App](https://getrush.ai/run/add-google-login/adonisjs/)
- [Add Health Checks to an AdonisJS API](https://getrush.ai/run/add-health-checks/adonisjs/)

## The same job on other stacks

- [Add File Uploads to a CodeIgniter 4 App](https://getrush.ai/run/add-file-uploads/codeigniter/)
- [Add File Uploads to a Livewire Component](https://getrush.ai/run/add-file-uploads/livewire/)
- [Add File Uploads to a React Router App](https://getrush.ai/run/add-file-uploads/react-router/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
