attachment

Attachment

File uploads are managed by @jrmc/adonis-attachment. A Lucid model declares an attachment field with @attachment({...}); uploads produce a stored file plus derived variants (thumbnails, previews, formats) driven by named converters in config/attachment.ts. Actions accept a MultipartFile from a validated form and call attachmentManager.createFromFile(file) to assign it. Storage is Drive (fs locally, S3-family in prod). URLs are pre-computed on read via a static model helper — always call it before serializing to Inertia so the frontend gets a real URL, not undefined.

Rules

• Field on model: decorate with @attachment({ preComputeUrl: false, variants: [...] }) and type as Attachment:

  @attachment({ preComputeUrl: false, variants: ['thumbnail'] })
  declare avatar: Attachment
  

  preComputeUrl: false keeps model reads cheap — URLs are computed on demand by the static helper.
• Converters live in config/attachment.ts as a keyed record. Each converter declares options (resize, format, etc.). The variant names in @attachment({ variants: [...] }) reference those keys.
• Declaration merge happens in the config file's declare module '@jrmc/adonis-attachment' block — that's how TypeScript knows variants: ['thumbnail'] is a valid key.
• Validate uploads with VineJS vine.file({...}):

  avatar: vine.file({ extnames: ['png', 'jpg', 'jpeg', 'gif'], size: 1 * 1024 * 1024 }).nullable()
  

• Persist inside an action — the action takes a MultipartFile (not HttpContext) and delegates to the manager:

  if (input.avatar) {
    input.target.avatar = await attachmentManager.createFromFile(input.avatar)
  }
  

  See [[actions-events]] for the "no HttpContext in actions" rule.
• Pre-compute URLs before serialization. Call the model's static helper on the loaded row (or list) before running the Transformer:

  await User.preComputeUrls(users)
  return inertia.render('users/index', {
    users: UserTransformer.paginate(users, meta).useVariant('forList'),
  })
  

  The Transformer variant reads the pre-computed URL from the loaded variant.
• Fallback URL: Transformers usually resolve variant.url ?? this.resource.<remoteUrl> so an externally-hosted URL (social-auth avatar, S3 direct link) works when no local upload exists.
• Drive config picks the disk (fs, s3, gcs, …). The DRIVE_DISK env var selects it.