Skip to main content
Thank you for your interest in contributing to the Inspira UI project! Your contributions help make this project better for everyone. Please take a moment to read through these guidelines to ensure a smooth collaboration.

​
Getting Started

1

Fork the Repository

Create a personal fork of the project on GitHub by visiting the Inspira UI repository.
2

Clone Your Fork

Clone your forked repository to your local machine:
git clone https://github.com/YOUR_USERNAME/inspira-ui.git
cd inspira-ui
3

Create a Branch

Create a new branch for your contribution:
git checkout -b feature/YourFeatureName
4

Install Dependencies

Run pnpm install to install all necessary dependencies:
pnpm install

​
Code of Conduct

By participating in this project, you agree to abide by the Code of Conduct, which aims to foster an open and welcoming environment.

​
How to Contribute

​
Reporting Bugs

If you find a bug, please open an issue and include:
  • A clear and descriptive title
  • Steps to reproduce the issue
  • Expected and actual results
  • Screenshots or code snippets, if applicable

​
Suggesting Enhancements

We welcome suggestions for new features or improvements. Please open an issue and include:
  • A clear and descriptive title
  • A detailed description of the enhancement
  • Any relevant examples or mockups

​
Adding New Components

We appreciate contributions that add new components to the library. Please ensure that:
  • The component is generally useful and aligns with the project’s goals
  • The component is compatible with both Nuxt and Vue
  • You follow the coding and documentation guidelines outlined below
  • You include unit tests for your component
Components Guidelines:
  1. Create or Update index.ts - Each folder under components/content/inspira/ui/<component-folder-name>/ should have an index.ts that exports all Vue files.
  2. Registry Dependencies - If your component depends on other Inspira UI components, update the COMPONENT_DEPENDENCIES map in ~/scripts/crawl-content.ts.
  3. Nuxt-Only Features - If your component uses Nuxt-only features like <ClientOnly>, mention this in the documentation.
  4. Avoid External Components - Don’t use external UI components that aren’t part of the core Vue.js ecosystem.
  5. Explicit Imports - Always include explicit imports in your component code for Vue.js compatibility.
  6. Icon Usage - Use the built-in <Icon> component rather than pasting raw SVGs.

​
Project Structure

Understanding the project structure is crucial for effective contribution: 
components/content/inspira/
├── ui/
│   └── <component-folder-name>/
│       ├── index.ts          # Exports all components
│       └── Component.vue     # Main component file
└── examples/
    └── <component-folder-name>/
        └── ComponentDemo.vue # Demo/example component

​
Style Guidelines

​
Coding Standards

  • Language: All components should be written in Vue.js with TypeScript support
  • Styling: Use Tailwind CSS classes for styling whenever possible
  • Naming Conventions: Use PascalCase for component names and filenames

​
Component Format

Your Vue components should adhere to the following structure: 
<script lang="ts" setup>
// Your script code goes here
</script>

<template>
  <!-- Your template code goes here -->
</template>

<style scoped>
/* Your styles go here */
</style>
Important Notes:
  • Use <script lang="ts" setup> for TypeScript and the Composition API
  • Keep styles scoped to prevent conflicts
  • Ensure compatibility with both Nuxt and Vue
  • Never use Enums; use {} as const instead
  • Constants must be CAPS_CAMEL_CASE with a prefix

​
Commit Messages

Use the Conventional Commits format:
  • Begin with a type (feat, fix, docs, etc.) followed by a short description
  • Example: feat: add TextHoverEffect component

​
Documentation Guidelines

​
Single-File Components

For components contained within a single .vue file:
1

Front Matter

Begin with YAML front matter:
---
title: Your Component Title
description: A brief description of what your component does.
---
2

Preview Section

Use the ComponentLoader to display a live preview:
::ComponentLoader{label="Preview" componentName="YourComponentDemo" type="examples" id="your-component-folder-name"}
::
3

Installation Instructions

Include both CLI and manual installation:
## Install using CLI

::InstallationCli{componentId="your-component-folder-name"}
::

## Install Manually

::CodeViewer{filename="YourComponent.vue" language="vue" componentName="YourComponent" type="ui" id="your-component-folder-name"}
::
4

API Documentation

Provide a table listing all props:
## API

| Prop Name | Type     | Default | Description           |
| --------- | -------- | ------- | --------------------- |
| `prop1`   | `string` | `''`    | Description of prop1. |

​
Multi-File Components

For components consisting of multiple files:
Use a ::code-group to group multiple CodeViewerTab components, one for each file.
## Install Manually

Copy and paste the following code in the same folder:

::code-group

:CodeViewerTab{label="MainComponent.vue" language="vue" componentName="MainComponent" type="ui" id="your-component-folder-name"}
:CodeViewerTab{filename="index.ts" language="typescript" componentName="index" type="ui" id="your-component-folder-name" extension="ts"}

::

​
Testing

Unit Tests

Write unit tests for your component if applicable to ensure functionality.

Cross-Environment

Test your component in both Nuxt and Vue environments.

Visual Testing

Check the component visually to ensure it renders correctly.

​
CLI Installation Testing

After updating the registry with pnpm build:registry, test the component installation: 
npx shadcn-vue@latest add "https://localhost:3000/r/<component-name>"

​
License

By contributing, you agree that your contributions will be licensed under the MIT License.
For more detailed information, check out the full CONTRIBUTING.md file in the repository.

Build docs developers (and LLMs) love

Get started for freeTalk to us