Contributing

Overview

Nuxt UI thrives thanks to its fantastic community ❤️, which contributes by submitting issues, creating pull requests, and offering valuable feedback.

Before reporting a bug or reporting a feature, please make sure that you have read through our documentation and existing issues.

Submitting a Pull Request

1. Before You Start

Check if there's an existing issue describing the problem or feature request you're working on. If there is, please leave a comment on the issue to let us know you're working on it.

If there isn't, open a new issue to discuss the problem or feature.

2. Local Development Setup

To begin local development, follow these steps:

1. Clone the nuxt/ui repository to your local machine:

git clone https://github.com/nuxt/ui.git

2. Install dependencies and prepare the project:

pnpm install
pnpm run dev:prepare

3. To configure your local development environment, use the following commands:

• To work on the documentation in the docs folder, run:

pnpm run dev

• To test the components located in the playground folder within app.vue, run:

pnpm run play

IDE Setup

We recommend using VS Code along with the ESLint extension. You can enable auto-fix and formatting when saving your code. Here's how:

{
  "editor.codeActionsOnSave": {
    "source.fixAll": false,
    "source.fixAll.eslint": true
  }
}

You can also use the lint command:

pnpm run lint # check for linting errors
pnpm run lint:fix # fix linting errors

No Prettier

Since ESLint is already configured to format the code, there's no need for duplicating functionality with Prettier.

If you have Prettier installed in your editor, we recommend disabling it to avoid conflicts.

Type Checking

We use TypeScript for type checking. You can use the typecheck command to check for type errors:

pnpm run typecheck

3. Commit Conventions

Use Conventional Commits for commit messages with the following format:

<type>(optional scope): <description>

[optional body]

[optional footer(s)]

Types

• feat : for new features.
• fix : for bug fixes.
• refactor : for code changes that are neither bug fixes nor new features.
• perf : for code refactoring that improves performance.
• test : for code related to automatic testing.
• style : for refactoring related to code style (not for CSS).
• docs : for changes related to documentation.
• chore : for anything else.

Scope

Where the change occurred (e.g., Table, Alert, Accordion, etc.).

Description

A summary of the changes made.

Examples

feat(Alert): new component
chore(Table): improve accessibility
docs: migrate to @nuxt/ui-pro

4. Making the Pull Request

• Follow the guide for creating a pull request and ensure your PR's title adheres to the Commit Convention. Mention any related issues in the PR description.
• Multiple commits are fine; no need to rebase or force push. We'll use Squash and Merge when merging.
• Ensure linting and make tests manually before submitting the PR. Avoid making unrelated changes.

5. After You've Made a Pull Request

We'll review it promptly. If assigned to a maintainer, they'll review it carefully. Ignore the red text; it's for tracking purposes.

Project Structure

In this project, you'll find a variety of folders and files that serve different purposes. Here's an overview of the main ones:

• Documentation - docs :

The documentation is located in the docs folder. It's a Nuxt app that uses the @nuxt/content module to generate the documentation pages from Markdown files. Here's a breakdown of its structure:

docs/
├── components/
│   ├── examples/     # Components used in documentation as examples
│   └── themes/       # Components used in the examples page in the theming section
├── content/          # Documentation, separated into categories according to component types
│   ├── 1.getting-started/
│   │   ├── 1.index.md
│   │   ├── 2.installation.md
│   │   ├── ... etc
│   ├── 2.elements/         # The category of components, which are elements
│   │   ├── 1.accordion.md  # Docs for a single component (i.e., accordion)
│   │   ├── 2.alert.md
│   │   ├── ... etc
└── ... etc

• Components - src :

The components are located in the src folder. It's separated into categories according to component types. Here's a breakdown of its structure:

src/
├── runtime/
│   ├── composables/            # Composable functions used in components
│   ├── components/             # Components folder, separated into categories according to component types
│   │   ├── data/               # The category of components, which are data related
│   │   │   ├── table.vue/      # Table component
│   │   │   ├── elements/       # Elements category
│   │   │   │   ├── ...etc/
│   │   │   └── ... etc/
│   │   ├── plugins/            # Plugins used in components
│   │   ├── utils/              # Utility functions used on the components page (e.g., lodash)
│   │   ├── types/              # Types used in components
│   │   │   ├── accordion.d.ts/ # [componentName].d.ts type used for single component
│   │   │   ├── avatar.d.ts/
│   │   │   └── ... etc/
│   │   ├── ui.config.ts/       # Configuration file used to apply styles to every component
├── colors.ts/                  # Everything related to color functions (e.g., safelistByComponent, generateSafelist)
└── ... etc/                    # Other files and folders

Thanks

Thank you again for being interested in this project! You are awesome! ❤️