Media Library

Media library components and upload utilities for Nuxt, Vue, and custom elements.

• ✨  Release Notes

Features

• ⛰  Foo
• 🚠  Bar
• 🌲  Baz

Quick Setup

Install the module to your Nuxt application with one command:

npx nuxi module add media-library

That's it! You can now use Media Library in your Nuxt app ✨

Usage

Nuxt installation (Vue components only)

export default defineNuxtConfig({
  modules: ['media-library'],
  mediaLibrary: {
    // Auto-register Vue components from src/runtime/components
    components: true,
    // Chunk uploader config (used by MlFileUpload)
    baseURL: 'https://api.example.com',
    // Uploads always go through Nuxt server (/api/media-library/uploads/*)
    routes: {
      createSession: '/uploads/sessions',
      getSession: '/uploads/sessions/:id',
      uploadPart: '/uploads/sessions/:id/parts/:part',
      finalize: '/uploads/sessions/:id/finalize',
      abort: '/uploads/sessions/:id/abort',
    },
    partSize: 8 * 1024 * 1024,
    concurrency: 3,
    checksum: { algorithm: 'SHA-256', perPart: true, final: true },
    headers: {},
  },
})

Nuxt usage

<template>
  <MediaLibrary />
</template>

If you use the uploader component in Nuxt, provide config via the Nuxt plugin (see your module/plugin setup) and use:

<template>
  <MlFileUpload />
</template>

Vue installation (non-Nuxt)

npm i media-library

import { createApp } from 'vue'
import MediaLibraryPlugin from 'media-library/vue'

const app = createApp(App)
app.use(MediaLibraryPlugin, {
  chunkUploader: {
    // Use a same-origin proxy (recommended) or set baseURL for direct calls
    baseURL: '',
    routes: {
      createSession: '/api/media-library/uploads/sessions',
      getSession: '/api/media-library/uploads/sessions/:id',
      uploadPart: '/api/media-library/uploads/sessions/:id/parts/:part',
      finalize: '/api/media-library/uploads/sessions/:id/finalize',
    },
    partSize: 8 * 1024 * 1024,
    concurrency: 3,
    checksum: { algorithm: 'SHA-256', perPart: true, final: true },
    headers: {},
  },
})

<template>
  <MediaLibrary />
  <MlFileUpload />
</template>

Custom element via CDN

Load the prebuilt custom element bundle (IIFE):

<script src="/dist-ce/media-library.custom-element.js"></script>
<media-library></media-library>
<ml-file-upload></ml-file-upload>

Global config:

<script>
  window.MediaLibraryConfig = {
    chunkUploader: {
      baseURL: '',
      routes: {
        createSession: '/api/media-library/uploads/sessions',
        getSession: '/api/media-library/uploads/sessions/:id',
        uploadPart: '/api/media-library/uploads/sessions/:id/parts/:part',
        finalize: '/api/media-library/uploads/sessions/:id/finalize',
      },
      partSize: 8388608,
      concurrency: 3,
      checksum: { algorithm: 'SHA-256', perPart: true, final: true },
      headers: {},
    }
  }
</script>

Per element:

<ml-file-upload
  chunk-uploader='{"baseURL":"","routes":{"createSession":"/api/media-library/uploads/sessions","getSession":"/api/media-library/uploads/sessions/:id","uploadPart":"/api/media-library/uploads/sessions/:id/parts/:part","finalize":"/api/media-library/uploads/sessions/:id/finalize"},"partSize":8388608,"concurrency":3,"checksum":{"algorithm":"SHA-256","perPart":true,"final":true},"headers":{}}'
></ml-file-upload>

Developer Guide

Nuxt development (module)

# Install dependencies
npm install

# Generate type stubs and prepare the playground
npm run dev:prepare

# Run the playground (Nuxt module usage)
npm run dev

Use the playground to test module options and auto-registered components.

SSR notes (Nuxt)

If a component uses browser-only APIs, use one of these patterns:

if (process.client) {
  // window/document usage
}

import { onMounted } from 'vue'

onMounted(() => {
  // safe to access window/document here
})

<ClientOnly>
  <MediaLibrary />
</ClientOnly>

Or make it client-only by naming the file MyComponent.client.vue.

Vue development (library)

# Build the Vue entry and type declarations
npm run prepack

Import from media-library/vue in a Vue app to verify component behavior.

Custom element development (CE)

# Build the standalone custom element bundle
npm run build:custom-element

Load dist-ce/media-library.custom-element.js in any HTML page and use <media-library></media-library> to verify the output.

Tests

npm run lint
npm run test
npm run test:watch
npm run test:types