Nuxt Upload KitNuxt Upload Kit
Get Started

Contributing

Learn how to contribute to Nuxt Upload Kit.

Contributing

Thank you for your interest in contributing to Nuxt Upload Kit! This guide will help you get started with development.

Prerequisites

Before you begin, ensure you have:

  • Node.js 18.x or 20.x (LTS recommended)
  • pnpm 10.x or later

Development Setup

Fork and Clone

Fork the repository on GitHub, then clone your fork:

Terminal
git clone https://github.com/YOUR_USERNAME/nuxt-upload-kit.git
cd nuxt-upload-kit

Install Dependencies

Terminal
pnpm install

Prepare Environment

Terminal
pnpm dev:prepare

Start Development Server

Terminal
pnpm dev

This starts a playground application where you can test your changes in real-time.

Project Structure

nuxt-upload-kit/
├── src/
│   ├── module.ts                    # Nuxt module entry point
│   └── runtime/
│       ├── types/index.ts           # Exported types
│       └── composables/
│           ├── useUploadKit/        # Main composable
│           │   ├── index.ts         # Core upload manager
│           │   ├── types.ts         # Type definitions
│           │   ├── validators/      # Validation plugins
│           │   └── plugins/         # Processing plugins
│           │       └── storage/     # Storage adapters
│           └── useFFMpeg.ts         # FFmpeg composable
├── playground/                      # Development playground
├── docs/                            # Documentation site
└── test/                            # Test files

Available Commands

CommandDescription
pnpm devStart dev server with playground
pnpm dev:preparePrepare development environment
pnpm testRun tests once
pnpm test:watchRun tests in watch mode
pnpm test:typesType-check with vue-tsc
pnpm lintRun ESLint
pnpm lint:fixFix ESLint issues
pnpm formatFormat with Prettier
pnpm docs:devRun documentation site locally
pnpm prepackBuild the module

Code Style

This project uses ESLint and Prettier with the following conventions:

  • No semicolons
  • Double quotes
  • Trailing commas
  • 130 character line width
  • TypeScript throughout
Run pnpm lint:fix && pnpm format before committing to ensure your code matches the project style.

Making Changes

Create a Branch

Create a descriptive branch for your changes:

Terminal
git checkout -b feature/my-new-feature
# or
git checkout -b fix/issue-description

Writing Tests

Tests are located in the test/ directory and use Vitest. Please include tests for any new features or bug fixes.

Terminal
pnpm test        # Run once
pnpm test:watch  # Watch mode

Type Checking

Ensure your changes pass type checking:

Terminal
pnpm test:types

Creating Plugins

One of the best ways to contribute is by creating new plugins. See the Custom Plugins and Custom Storage Adapters guides for detailed instructions.

Validator Plugin Example

export const ValidatorExample = defineProcessingPlugin<{ option: string }>((options) => ({
  id: "validator-example",
  hooks: {
    validate: async (file, context) => {
      // Return file to pass, throw to reject
      return file
    },
  },
}))

Storage Plugin Example

export const PluginStorageExample = (options: Options): StoragePlugin => ({
  id: "storage-example",
  hooks: {
    upload: async (file, context) => {
      // Upload logic, call context.onProgress(0-100)
      return { url: "...", ...metadata }
    },
    getRemoteFile: async (fileId, context) => {
      return { size, mimeType, remoteUrl }
    },
    remove: async (file, context) => {
      // Delete from storage
    },
  },
})

Documentation

Documentation lives in the docs/ directory and uses Docus.

To run the documentation site locally:

Terminal
pnpm docs:dev

When adding new features, please update the relevant documentation.

Submitting a Pull Request

Verify Your Changes

Before submitting, ensure:

Terminal
pnpm test        # All tests pass
pnpm lint:fix    # No linting errors
pnpm format      # Code is formatted
pnpm test:types  # Types are correct

Push and Create PR

Push your branch and create a pull request on GitHub:

Terminal
git push origin feature/my-new-feature

Describe Your Changes

Provide a clear description including:

  • What changes you made
  • Why you made them
  • Any related issues

Commit Message Guidelines

Use clear, descriptive commit messages:

PrefixUse Case
feat:New features
fix:Bug fixes
docs:Documentation changes
refactor:Code refactoring
test:Adding or updating tests
chore:Maintenance tasks

Examples:

  • feat: add new storage adapter for S3
  • fix: resolve thumbnail generation for large images
  • docs: update configuration guide

Reporting Issues

When reporting issues, please include:

  • Your Node.js and pnpm versions
  • Your Nuxt version
  • Steps to reproduce the issue
  • Expected vs actual behavior
  • Any error messages or logs
Check existing issues before creating a new one to avoid duplicates.

Questions?

If you have questions about contributing, feel free to open an issue or start a discussion on GitHub.

License

By contributing to Nuxt Upload Kit, you agree that your contributions will be licensed under the MIT License.

Configuration

Configure Nuxt Upload Kit to fit your application needs.

Overview

The core composable for managing file uploads in your Nuxt application.

Copyright © 2026