nuxt-uploads

Simple file uploads for Nuxt. Zero-config file storage with Nitro.

---

• Release Notes

Features

• Zero Config - Just set a path, the module handles the rest
• Nitro Storage - Automatic storage configuration
• Auto Validation - File size and type validation out of the box
• Serve Route - Optional automatic route to serve uploaded files
• Type Safe - Full TypeScript support

Quick Setup

Install the module:

npx nuxi module add nuxt-uploads

Add configuration to your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['nuxt-uploads'],
  uploads: {
    basePath: './uploads',
  },
})

That's it! You can now use useUploads() in your server routes.

Usage

Basic Upload

// server/api/upload.post.ts
export default defineEventHandler(async (event) => {
  return await useUploads().save(event)
})

This returns:

[
  {
    "key": "1702847123456-abc123.jpg",
    "originalName": "photo.jpg",
    "size": 45000,
    "type": "image/jpeg"
  }
]

Serve Uploaded Files

Enable the serve route in your config:

export default defineNuxtConfig({
  uploads: {
    basePath: './uploads',
    serve: '/uploads', // Files accessible at /uploads/:key
  },
})

Now files are available at http://localhost:3000/uploads/1702847123456-abc123.jpg

Full API

const uploads = useUploads()

// Save files from form data
const saved = await uploads.save(event)

// Save with custom options
const saved = await uploads.save(event, {
  key: 'custom-name.jpg',        // Custom key instead of UUID
  maxSize: 5 * 1024 * 1024,      // Override max size
  allowedTypes: ['image/png'],   // Override allowed types
})

// Get file data
const buffer = await uploads.get('file-key.jpg')

// Delete a file
await uploads.remove('file-key.jpg')

// List all files
const keys = await uploads.list()

// Check if file exists
const exists = await uploads.exists('file-key.jpg')

// Access raw storage (for advanced use)
uploads.storage

Configuration

export default defineNuxtConfig({
  uploads: {
    // Base path for file storage (required)
    basePath: './uploads',

    // Maximum file size in bytes (default: 10MB)
    maxSize: 10 * 1024 * 1024,

    // Allowed MIME types (default: ['*'] = all)
    // Supports wildcards like 'image/*'
    allowedTypes: ['image/*', 'application/pdf'],

    // Serve route path (default: false = disabled)
    serve: '/uploads',

    // Custom MIME type mappings (extends defaults)
    mimeTypes: {
      avif: 'image/avif',
      heic: 'image/heic',
    },
  },
})

Client-Side Upload Example

<script setup>
async function upload(event) {
  const file = event.target.files[0]
  const formData = new FormData()
  formData.append('file', file)

  const result = await $fetch('/api/upload', {
    method: 'POST',
    body: formData,
  })

  console.log('Uploaded:', result)
}
</script>

<template>
  <input type="file" @change="upload">
</template>

Contribution

Local development

# Install dependencies
pnpm install

# Generate type stubs
pnpm dev:prepare

# Develop with the playground
pnpm dev

# Build the playground
pnpm dev:build

# Run ESLint
pnpm lint

# Run Vitest
pnpm test
pnpm test:watch

# Release new version
pnpm release

License

MIT License