@jrmc/adonis-attachment

AdonisJS attachment

This package is currently development and will replace attachment-advanced for AdonisJS 6.

Project sample : adonis-starter-kit

Roadmap

• attachment file by file system
• save meta data
• variantes
  • images
  • documents thumbnail
  • videos thumbnail
• command regenerate
• adonis-drive/flydrive
• jobs queue
• edge component
• serialize

⚠️ Breaking change, include @adonisjs/drive

File sytem

Upload file in public folder.

Meta data list (if available)

• extension name
• size
• dimension (width, height)
• created date
• orientation
• mime type
• gps

Variants

Configure differents images sizes and formats

Regenerate (coming soon)

Regenerate variantes files

Drive

Use @adonisjs/drive for private file and cloud services

Jobs queue (coming soon)

Couple with a job queue (recommended, optional)

Setup

Install and configure the package:

node ace add @jrmc/adonis-attachment@beta

Or:

npm i @jrmc/adonis-attachment@beta
node ace configure @jrmc/adonis-attachment

Usage

Often times, the size of the image metadata could exceed the allowable length of an SQL String data type. So, it is recommended to create/modify the column which will hold the metadata to use a JSON data type.

If you are creating the column for the first time, make sure that you use the JSON data type. Example:

  // Within the migration file

  protected tableName = 'users'

  public async up() {
    this.schema.createTable(this.tableName, (table) => {
      table.increments()
      table.json('avatar') // <-- Use a JSON data type
    })
  }

If you already have a column for storing image paths/URLs, you need to create a new migration and alter the column definition to a JSON data type. Example:

# Create a new migration file
node ace make:migration change_avatar_column_to_json --table=users

  // Within the migration file

  protected tableName = 'users'

  public async up() {
    this.schema.alterTable(this.tableName, (table) => {
      table.json('avatar').alter() // <-- Alter the column definition
    })
  }

Next, in the model, import the attachment decorator, Attachmentable mixin and the Attachment type from the package.

Make sure NOT to use the @column decorator when using the @attachment decorator.

import { BaseModel } from '@adonisjs/lucid/orm'
import { compose } from '@adonisjs/core/helpers'
import { attachment, Attachmentable } from '@jrmc/adonis-attachment'
import type { Attachment } from '@jrmc/adonis-attachment/types/attachment'

class User extends compose(BaseModel, Attachmentable) {
  @attachment()
  declare avatar: Attachment
}

Now you can create an attachment from the user uploaded file as follows.

import { attachmentManager } from '@jrmc/adonis-attachment'

class UsersController {
  public store({ request }: HttpContext) {
    const avatar = request.file('avatar')!
    const user = new User()

    user.avatar = await attachmentManager.createFromFile(avatar)
    // user.avatar = await attachmentManager.createFromBuffer(buffer, 'photo.jpg')
    await user.save()
  }
}

Specifying subfolder

You can also store files inside the subfolder by defining the folder property as follows.

class User extends BaseModel {
  @attachment({ folder: 'uploads/avatars' })
  declare avatar: Attachment
}

Specifying variants

It is possible to limit the variants on an attachment

class User extends BaseModel {
  @attachment({
    variants: ['thumbnail', 'medium', 'large']
  })
  declare avatar: Attachment
}

URLs

await user.avatar.getUrl()
await user.avatar.getUrl('thumbnail')
// or await user.avatar.getVariant('thumbnail').getUrl()

await user.avatar.getSignedUrl()
await user.avatar.getSignedUrl('thumbnail')
// or await user.avatar.getVariant('thumbnail').getSignedUrl()

<img src="{{ await user.avatar.getUrl('thumbnail') }}" loading="lazy" alt="" />

<img src="{{ await user.avatar.getSignedUrl() }}" loading="lazy" alt="" />
<img src="{{ await user.avatar.getSignedUrl({
  expiresIn: '30 mins',
}) }}" loading="lazy" alt="" />

<img src="{{ await user.avatar.getSignedUrl('thumbnail') }}" loading="lazy" alt="" />
<img src="{{ await user.avatar.getSignedUrl('thumbnail', {
  expiresIn: '30 mins',
}) }}" loading="lazy" alt="" />

getSignedUrl options params accepts expiresIn, contentType et contentDisposition. More informations

by serialize

await user.avatar.toJSON()

<img :src="user.avatar.thumbnail.url" loading="lazy" alt="" />
<img :src="user.avatar.thumbnail.signedUrl" loading="lazy" alt="" />

Configuration

Configuration for variants files (config/attachment.ts)

import { defineConfig } from '@jrmc/adonis-attachment'
import app from '@adonisjs/core/services/app'
import sharp from 'sharp'

export default defineConfig({
  converters: [
    {
      key: 'thumbnail',
      converter: () => import('@jrmc/adonis-attachment/converters/image_converter'),
      options: {
        resize: 300,
        format: 'webp',
      }
    },
    {
      key: 'medium',
      converter: () => import('@jrmc/adonis-attachment/converters/image_converter'),
      options: {
        format: 'jpeg',
        resize: { // https://sharp.pixelplumbing.com/api-resize
          width: 400,
          height: 400,
          fit: sharp.fit.cover,
          position: 'top'
        },
      }
    },
    {
      key: 'large',
      converter: () => import('@jrmc/adonis-attachment/converters/image_converter'),
      options: {
        resize: 1024,
        format: {
          format: 'png',
          options: {
            quality: 80
          }
        }

      }
    },
    {
      key: 'preview',
      converter: () => import('@jrmc/adonis-attachment/converters/video_thumbnail_converter'),
      options: {
        format: 'jpeg',
        resize: 720
      }
    },
  ]
})

Variants images are generates by sharp module

Options resize is number or object(options) details in documentation : sharp api resize

Options format is string or object [ format, options ] details in documentation : sharp api outpout

npm install sharp

Variants thumbnail videos are generate by fluent-ffmpeg

By default, image format is PNG and size is video size. options attribute use image_converter (and sharp)

npm install fluent-ffmpeg