arthur/ui
1
0
Fork 0
mirror of https://github.com/ArthurDanjou/ui.git synced 2026-01-22 07:50:36 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs(deps): update @nuxt/content and move content/ outside of app/

Browse Source
This commit is contained in:
Benjamin Canac
2024-06-20 10:39:10 +02:00
parent 11ef256db7
commit 0b8bfa887b
52 changed files with 61 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

266
docs/content/1.getting-started/2.installation.md Normal file
View File

@@ -0,0 +1,266 @@
---
title: Installation
description: 'Learn how to install and configure Nuxt UI in your application.'
---
## Setup
1. Install `@nuxt/ui` dependency to your project:
::code-group
```bash [pnpm]
pnpm add @nuxt/ui
```
```bash [yarn]
yarn add @nuxt/ui
```
```bash [npm]
npm install @nuxt/ui
```
```bash [bun]
bun add @nuxt/ui
```
::
2. Add it to your `modules` section in your `nuxt.config`:
```ts [nuxt.config.ts]
export default defineNuxtConfig({
modules: ['@nuxt/ui']
})
```
That's it! You can now use all the components and composables in your Nuxt app ✨
## Modules
Nuxt UI will automatically install the [@nuxtjs/tailwindcss](https://tailwindcss.nuxtjs.org/), [@nuxtjs/color-mode](https://color-mode.nuxtjs.org/) and [nuxt-icon](https://github.com/nuxt-modules/icon) modules for you.
::callout{icon="i-heroicons-exclamation-triangle"}
You should remove them from your `modules` and `dependencies` if you've previously installed them.
::
### `@nuxtjs/tailwindcss`
This module is pre-configured and will automatically load the following plugins:
- [@tailwindcss/forms](https://github.com/tailwindlabs/tailwindcss-forms)
- [@tailwindcss/typography](https://github.com/tailwindlabs/tailwindcss-typography)
- [@tailwindcss/aspect-ratio](https://github.com/tailwindlabs/tailwindcss-aspect-ratio)
- [@tailwindcss/container-queries](https://github.com/tailwindlabs/tailwindcss-container-queries)
- [@headlessui/tailwindcss](https://github.com/tailwindlabs/headlessui/tree/main/packages/%40headlessui-vue)
Note that the `@tailwindcss/aspect-ratio` plugin disables the default aspect ratio utilities:
- `aspect-auto`
- `aspect-square`
- `aspect-video`
You can re-enable them by adding the following to your `tailwind.config.ts`:
```ts [tailwind.config.ts]
import type { Config } from 'tailwindcss'
export default <Partial<Config>>{
theme: {
extend: {
aspectRatio: {
auto: 'auto',
square: '1 / 1',
video: '16 / 9'
}
}
}
}
```
### `@nuxtjs/color-mode`
This module is installed to provide dark mode support out of the box thanks to the Tailwind CSS dark mode `class` strategy.
::callout{icon="i-heroicons-light-bulb"}
You can read more about this in the [Theming](/getting-started/theming#dark-mode) section.
::
### `nuxt-icon`
This module is installed when using the `dynamic` prop on the `Icon` component or globally through the `ui.icons.dynamic` option in your `app.config.ts`.
::callout{icon="i-heroicons-light-bulb"}
You can read more about this in the [Theming](/getting-started/theming#dynamic-icons) section and on the [Icon](/components/icon) component page.
::
## TypeScript
This module is written in TypeScript and provides typings for all the components and composables. You can look at the [source code](https://github.com/nuxt/ui/tree/dev/src/runtime/types) to see all the available types.
::callout{icon="i-heroicons-light-bulb" to="https://nuxt.com/docs/guide/concepts/typescript" target="_blank"}
You can read more about TypeScript on the official Nuxt documentation.
::
You can use those types in your own components by importing them from `#ui/types`, for example when defining wrapper components:
```vue
<template>
<UBreadcrumb :links="links">
<template #icon="{ link }">
<UIcon :name="link.icon" />
</template>
</UBreadcrumb>
</template>
<script setup lang="ts">
import type { BreadcrumbLink } from '#ui/types'
export interface Props {
links: BreadcrumbLink[]
}
defineProps<Props>()
</script>
```
You don't have to use TypeScript yourself, but doing so will give you access to prop validation and autocomplete.
We've managed to provide dynamic typings on props such as `color`, `size`, `variant`, etc. based on your custom config. For example, you'll be suggested the `custom` color and the `subtle` variant when using the `Button` component with an `app.config.ts` as such:
```ts [app.config.ts]
export default defineAppConfig({
ui: {
button: {
color: {
custom: {
subtle: '...'
}
}
}
}
})
```
::callout{icon="i-heroicons-light-bulb"}
You can read more about components configuration in the [Theming](/getting-started/theming#appconfigts) section.
::
## IntelliSense
If you're using VSCode, you can install the [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) extension to get autocompletion for the classes.
You can read more on how to set it up on the [@nuxtjs/tailwindcss](https://tailwindcss.nuxtjs.org/tailwind/editor-support) module documentation, but to summarize, you'll need to add the following to your `.vscode/settings.json`:
```json [.vscode/settings.json]
{
"files.associations": {
"*.css": "tailwindcss"
},
"editor.quickSuggestions": {
"strings": true
}
}
```
You can write your `tailwind.config` in TypeScript as such:
```ts [tailwind.config.ts]
import type { Config } from 'tailwindcss'
export default <Partial<Config>> {
content: [
'docs/content/**/*.md'
]
}
```
If you do so, you'll need to add the following to your `.vscode/settings.json`:
```json [.vscode/settings.json]
{
"tailwindCSS.experimental.configFile": "tailwind.config.ts"
}
```
Note, the extension won't work when writing classes in your `app.config.ts` by default.
Also, you might want IntelliSense on objects in your SFC by prefixing with `/*ui*/`.
To enable these two features, you can add the following to your `.vscode/settings.json`:
```json [.vscode/settings.json]
{
"tailwindCSS.experimental.classRegex": [
["ui:\\s*{([^)]*)\\s*}", "[\"'`]([^\"'`]*).*?[\"'`]"],
["/\\*\\s?ui\\s?\\*/\\s*{([^;]*)}", ":\\s*[\"'`]([^\"'`]*).*?[\"'`]"]
]
}
```
An example SFC using IntelliSense (note the `/*ui*/` prefix, also works with `ref()`):
```vue [example.vue]
<template>
<UCard :ui="ui" />
</template>
<script setup lang="ts">
const ui = /* ui */ {
background: 'bg-white dark:bg-slate-900'
}
</script>
```
You can also add the following to your `.vscode/settings.json` to enable IntelliSense when using the `ui` prop:
```json [.vscode/settings.json]
{
"tailwindCSS.classAttributes": [
"class",
"className",
"ngClass",
"ui"
]
}
```
## Options
| Key | Default | Description |
|-----------------------|-----------------|-------------------------------------------------------------------------------------------------------------|
| `prefix` | `u` | Define the prefix of the imported components. |
| `global` | `false` | Expose components globally. |
| `icons` | `['heroicons']` | Icon collections to load. |
| `safelistColors` | `['primary']` | Force safelisting of colors to need be purged. |
| `disableGlobalStyles` | `false` | Disable [global CSS styles](https://github.com/nuxt/ui/blob/dev/src/runtime/ui.css) injected by the module. |
Configure options in your `nuxt.config.ts` as such:
```ts [nuxt.config.ts]
export default defineNuxtConfig({
modules: ['@nuxt/ui'],
ui: {
global: true,
icons: ['mdi', 'simple-icons']
}
})
```
## Edge
To use the latest updates pushed on the [`dev`](https://github.com/nuxt/ui/tree/dev) branch, you can use `@nuxt/ui-edge`.
Update your `package.json` to the following:
```diff [package.json]
{
"devDependencies": {
- "@nuxt/ui": "^2.11.0"
+ "@nuxt/ui": "npm:@nuxt/ui-edge@latest"
}
}
```
Then run `pnpm install`, `yarn install` or `npm install`.

184
docs/content/1.getting-started/3.theming.md Normal file
View File

@@ -0,0 +1,184 @@
---
description: 'Learn how to customize the look and feel of the components.'
---
This module relies on Nuxt [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file) file to customize the look and feel of the components at runtime with HMR (hot-module-replacement).
## Colors
### Configuration
Components are based on a `primary` and a `gray` color. You can change them in your `app.config.ts`.
```ts [app.config.ts]
export default defineAppConfig({
ui: {
primary: 'green',
gray: 'cool'
}
})
```
::callout{icon="i-heroicons-light-bulb"}
Try to change the `primary` and `gray` colors by clicking on the :u-icon{name="i-heroicons-swatch-20-solid" class="w-4 h-4 align-middle text-primary-500 dark:text-primary-400"} button in the header.
::
As this module uses Tailwind CSS under the hood, you can use any of the [Tailwind CSS colors](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) or your own custom colors. By default, the `primary` color is `green` and the `gray` color is `cool`.
When [using custom colors](https://tailwindcss.com/docs/customizing-colors#using-custom-colors) or [adding additional colors](https://tailwindcss.com/docs/customizing-colors#adding-additional-colors) through the `extend` key in your `tailwind.config.ts`, you'll need to make sure to define all the shades from `50` to `950` as most of them are used in the components config defined in [`ui.config/`](https://github.com/nuxt/ui/tree/dev/src/runtime/ui.config) directory. You can [generate your colors](https://tailwindcss.com/docs/customizing-colors#generating-colors) using tools such as https://uicolors.app/ for example.
```ts [tailwind.config.ts]
import type { Config } from 'tailwindcss'
import defaultTheme from 'tailwindcss/defaultTheme'
export default <Partial<Config>>{
theme: {
extend: {
colors: {
green: {
50: '#EFFDF5',
100: '#D9FBE8',
200: '#B3F5D1',
300: '#75EDAE',
400: '#00DC82',
500: '#00C16A',
600: '#00A155',
700: '#007F45',
800: '#016538',
900: '#0A5331',
950: '#052e16'
}
}
}
}
}
```
### CSS Variables
To provide dynamic colors that can be changed at runtime, this module uses CSS variables. As Tailwind CSS already has a `gray` color, the module automatically renames it to `cool` to avoid conflicts (`coolGray` was renamed to `gray` when Tailwind CSS v3.0 was released).
Likewise, you can't define a `primary` color in your `tailwind.config.ts` as it would conflict with the `primary` color defined by the module.
::callout{icon="i-heroicons-light-bulb"}
We'd advise you to use those colors in your components and pages, e.g. `text-primary-500 dark:text-primary-400`, `bg-gray-100 dark:bg-gray-900`, etc. so your app automatically adapts when changing your `app.config.ts`.
::
The `primary` color also has a `DEFAULT` shade that changes based on the theme. It is `500` in light mode and `400` in dark mode. You can use as a shortcut in your components and pages, e.g. `text-primary`, `bg-primary`, `focus-visible:ring-primary`, etc.
## Components
### `app.config.ts`
You can find the config of each component in the [`ui.config/`](https://github.com/nuxt/ui/tree/dev/src/runtime/ui.config) directory. You can override those classes in your own `app.config.ts`.
```ts [app.config.ts]
export default defineAppConfig({
ui: {
container: {
constrained: 'max-w-5xl'
}
}
})
```
Thanks to [tailwind-merge](https://github.com/dcastil/tailwind-merge), the `app.config.ts` is smartly merged with the default config. This means you don't have to rewrite everything.
You can change this behavior by setting `strategy` to `override` in your `app.config.ts`:
```ts [app.config.ts]
export default defineAppConfig({
ui: {
strategy: 'override',
button: {
color: {
white: {
solid: 'bg-white dark:bg-gray-900'
}
}
}
}
})
```
### `ui` prop
Each component has a `ui` prop that allows you to customize everything specifically.
```vue
<template>
<UContainer :ui="{ constrained: 'max-w-2xl' }">
<slot />
</UContainer>
</template>
```
::callout{icon="i-heroicons-light-bulb"}
You can find the default classes for each component under the `Config` section.
::
Thanks to [tailwind-merge](https://github.com/dcastil/tailwind-merge), the `ui` prop is smartly merged with the config. This means you don't have to rewrite everything.
For example, the default preset of the `FormGroup` component looks like this:
```json
{
"label": {
"base": "block font-medium text-gray-700 dark:text-gray-200"
}
}
```
To change the font of the `label`, you only need to write:
```vue
<UFormGroup name="email" label="Email" :ui="{ label: { base: 'font-semibold' } }" />
```
This will smartly replace the `font-medium` by `font-semibold` and prevent any class duplication and any class priority issue.
You can change this behavior by setting `strategy` to `override` inside the `ui` prop:
```vue
<UButton
to="https://github.com/nuxt/ui"
:ui="{
strategy: 'override',
color: {
white: {
solid: 'bg-white dark:bg-gray-900'
}
}
}"
/>
```
### `class` attribute
You can also use the `class` attribute to add classes to the component.
```vue
<template>
<UButton label="Button" class="rounded-full" />
</template>
```
Again, with [tailwind-merge](https://github.com/dcastil/tailwind-merge), this will smartly merge the classes with the `ui` prop and the config.
### Default values
Some component props like `size`, `color`, `variant`, etc. have a default value that you can override in your `app.config.ts`.
```ts [app.config.ts]
export default defineAppConfig({
ui: {
button: {
default: {
size: 'md',
color: 'gray',
variant: 'ghost'
}
}
}
})
```

195
docs/content/1.getting-started/4.icons.md Normal file
View File

@@ -0,0 +1,195 @@
---
description: ''
---
You can use any icon (100,000+) from [Iconify](https://iconify.design/).
Some components have an `icon` prop that allows you to add an icon to the component.
```vue
<template>
<UButton icon="i-heroicons-magnifying-glass" />
</template>
```
You can also use the [Icon](/components/icon) component to add an icon anywhere in your app by following this pattern: `i-{collection_name}-{icon_name}`.
```vue
<template>
<UIcon name="i-heroicons-moon" />
</template>
```
### Collections
By default, the module uses [Heroicons](https://heroicons.com/) but you can change it from the module options in your `nuxt.config.ts`.
```ts [nuxt.config.ts]
export default defineNuxtConfig({
ui: {
icons: ['mdi', 'simple-icons']
}
})
```
::callout{icon="i-heroicons-light-bulb"}
Search the icon you want to use on https://icones.js.org built by [@antfu](https://github.com/antfu).
::
Thanks to [@egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons) plugin, only the icons you use in your app will be bundled in your CSS. However, you need to install the icon collections you specified in the `ui.icons` key:
::code-group
```bash [pnpm]
pnpm i @iconify-json/{collection_name}
```
```bash [yarn]
yarn add @iconify-json/{collection_name}
```
```bash [npm]
npm install @iconify-json/{collection_name}
```
::
If you choose to use the full `@iconify/json` icon collection (50MB), you can specifiy `icons: 'all'` or `icons: {}` in your `nuxt.config.ts` to use any icon in your app.
```ts [nuxt.config.ts]
export default defineNuxtConfig({
ui: {
icons: {}
}
})
```
### Custom config
If you have specific needs, like using a custom icon collection, you can use the `icons` option in your `nuxt.config.ts` as an object to override the config of the [@egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons#plugin-options) plugin.
```ts [nuxt.config.ts]
import { getIconCollections } from '@egoist/tailwindcss-icons'
export default defineNuxtConfig({
ui: {
icons: {
// might solve stretch bug on generate, see https://github.com/egoist/tailwindcss-icons/issues/23
extraProperties: {
'mask-size': 'contain',
'mask-position': 'center'
},
collections: {
foo: {
icons: {
'arrow-left': {
// svg body
body: '<path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="1.5" d="M10.5 19.5L3 12m0 0l7.5-7.5M3 12h18" />',
// svg width and height, optional
width: 24,
height: 24
}
}
},
...getIconCollections(['heroicons', 'simple-icons'])
}
}
}
})
```
### Dynamic icons
The `Icon` component also has a `dynamic` prop to use the [nuxt-icon](https://github.com/nuxt-modules/icon/) module instead of the [@egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons#plugin-options) plugin.
Read more about this in the [Icon](/components/icon#dynamic) component page.
### Defaults
You can easily replace all the default icons of the components in your `app.config.ts`.
```ts [app.config.ts]
export default defineAppConfig({
ui: {
button: {
default: {
loadingIcon: 'i-octicon-sync-24'
}
},
input: {
default: {
loadingIcon: 'i-octicon-sync-24'
}
},
select: {
default: {
loadingIcon: 'i-octicon-sync-24',
trailingIcon: 'i-octicon-chevron-down-24'
}
},
selectMenu: {
default: {
selectedIcon: 'i-octicon-check-24'
}
},
notification: {
default: {
closeButton: {
icon: 'i-octicon-x-24'
}
}
},
commandPalette: {
default: {
icon: 'i-octicon-search-24',
loadingIcon: 'i-octicon-sync-24',
selectedIcon: 'i-octicon-check-24',
emptyState: {
icon: 'i-octicon-search-24'
}
}
},
table: {
default: {
sortAscIcon: 'i-octicon-sort-asc-24',
sortDescIcon: 'i-octicon-sort-desc-24',
sortButton: {
icon: 'i-octicon-arrow-switch-24'
},
loadingState: {
icon: 'i-octicon-sync-24'
},
emptyState: {
icon: 'i-octicon-database-24'
}
}
},
pagination: {
default: {
firstButton: {
icon: 'i-octicon-chevron-left-24'
},
prevButton: {
icon: 'i-octicon-arrow-left-24'
},
nextButton: {
icon: 'i-octicon-arrow-right-24'
},
lastButton: {
icon: 'i-octicon-chevron-right-24'
}
}
},
accordion: {
default: {
openIcon: 'i-octicon-chevron-down-24'
}
},
breadcrumb: {
default: {
divider: 'i-octicon-chevron-right-24'
}
}
}
})
```

58
docs/content/1.getting-started/5.dark-mode.md Normal file
View File

@@ -0,0 +1,58 @@
---
title: 'Dark mode'
description: ''
---
All the components are styled with dark mode in mind.
Thanks to [Tailwind CSS dark mode](https://tailwindcss.com/docs/dark-mode#toggling-dark-mode-manually) class strategy and the [@nuxtjs/color-mode](https://github.com/nuxt-modules/color-mode) module, you literally have nothing to do.
You can disable dark mode by setting the `preference` to `light` instead of `system` in your `nuxt.config.ts`.
```ts [nuxt.config.ts]
export default defineNuxtConfig({
colorMode: {
preference: 'light'
}
})
```
::callout{icon="i-heroicons-light-bulb"}
If you're stuck in dark mode even after changing this setting, you might need to remove the `nuxt-color-mode` entry from your browser's local storage.
::
You can easily build a color mode button by using the `useColorMode` composable from `@nuxtjs/color-mode`.
::component-example
#default
:color-mode-button
#code
```vue
<script setup lang="ts">
const colorMode = useColorMode()
const isDark = computed({
get () {
return colorMode.value === 'dark'
},
set () {
colorMode.preference = colorMode.value === 'dark' ? 'light' : 'dark'
}
})
</script>
<template>
<ClientOnly>
<UButton
:icon="isDark ? 'i-heroicons-moon-20-solid' : 'i-heroicons-sun-20-solid'"
color="gray"
variant="ghost"
aria-label="Theme"
@click="isDark = !isDark"
/>
<template #fallback>
<div class="w-8 h-8" />
</template>
</ClientOnly>
</template>
```
::

141
docs/content/1.getting-started/6.shortcuts.md Normal file
View File

@@ -0,0 +1,141 @@
---
description: 'Learn how to display and define keyboard shortcuts in your app.'
---
Some components like [Dropdown](/components/dropdown), [Command Palette](/components/command-palette) and [Tooltip](/components/tooltip) support the display of keyboard shortcuts.
```vue
<UDropdown :items="[[{ label: 'Edit', shortcuts: ['E'] }]]" />
```
Shortcuts are displayed and styled through the [Kbd](/components/kbd) component.
```vue
<template>
<div class="flex items-center gap-0.5">
<UKbd>⌘</UKbd>
<UKbd>K</UKbd>
</div>
</template>
```
::callout{icon="i-heroicons-light-bulb"}
You will have a preview of how shortcuts are rendered in each component page.
::
## `defineShortcuts`
This module provides a `defineShortcuts` composable that allows you to define keyboard shortcuts in your app really easily.
```vue
<template>
<UModal v-model="isOpen" />
</template>
<script setup lang="ts">
const isOpen = ref(false)
defineShortcuts({
meta_k: {
usingInput: true,
handler: () => {
isOpen.value = !isOpen.value
}
}
})
</script>
```
Shortcuts keys are written as the literal keyboard key value. Combinations are made with `_` separator. Chained shortcuts are made with `-` separator.
Modifiers are also available:
- `meta`: acts as `Command` for MacOS and `Control` for others
- `ctrl`: acts as `Control`
- `shift`: acts as `Shift` and is only necessary for alphabetic keys
Examples of keys:
- `escape`: will trigger by hitting `Esc`
- `meta_k`: will trigger by hitting `⌘` and `K` at the same time on MacOS, and `Ctrl` and `K` on Windows and Linux
- `ctrl_k`: will trigger by hitting `Ctrl` and `K` at the same time on MacOS, Windows and Linux
- `shift_e`: will trigger by hitting `Shift` and `E` at the same time on MacOS, Windows and Linux
- `?`: will trigger by hitting `?` on some keyboard layouts, or for example `Shift` and `/`, which results in `?` on US Mac keyboards
- `g-d`: will trigger by hitting `g` then `d` with a maximum delay of 800ms by default
- `arrowleft`: will trigger by hitting `←` (also: `arrowright`, `arrowup`, `arrowdown`)
::callout{icon="i-heroicons-light-bulb"}
For a complete list of available shortcut keys, refer to the [`KeyboardEvent`](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) API docs. Note the `KeyboardEvent.key` has to be written in lowercase.
::
### `usingInput`
Prop: `usingInput?: string | boolean`
By default, `usingInput` is `false`, meaning it will only trigger when no input is focused. When set to `true`, the shortcut will also trigger when any input is focused.
For a more advanced behavior, `usingInput` can be set to the name of an input, so it only triggers when focusing this specific input.
```vue
<template>
<UInput v-model="query" name="queryInput" />
</template>
<script setup lang="ts">
const query = ref('')
defineShortcuts({
enter: {
usingInput: 'queryInput',
handler: () => {
// TODO
}
}
})
</script>
```
_`enter` shortcut will only trigger when `queryInput` is focused._
### `whenever`
Prop: `whenever?: WatchSource<boolean>[]`
`whenever` allows to add constraints on the shortcut triggering behavior. This array can contain `Ref<boolean>`, `ComputedRef<boolean>` or `() => boolean`.
```ts
defineShortcuts({
meta_k: {
usingInput: true,
handler: () => { isOpen.value = !isOpen.value }
},
escape: {
usingInput: true,
whenever: [isOpen],
handler: () => { isOpen.value = false }
}
})
```
_`escape` shortcut will only trigger when `isOpen` is `true`._
### Simple shortcut
In case the shortcut does not need any config, it can be written as a function.
```ts
defineShortcuts({
'?': () => openHelpModal()
})
```
## `useShortcuts`
To display shortcuts in your app according to the user's OS, you can use the `useShortcuts` composable.
```vue
<script setup lang="ts">
const { metaSymbol } = useShortcuts()
</script>
<template>
<UKbd>{{ metaSymbol }}</UKbd>
</template>
```
_`metaSymbol` will display either `⌘` on MacOS or `Ctrl` on any other OS_

178
docs/content/1.getting-started/7.contributing.md Normal file
View File

@@ -0,0 +1,178 @@
---
title: Contributing
description: Learn how to contribute to Nuxt UI.
navigation: false
---
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](https://github.com/nuxt/ui/issues).
## Submitting a Pull Request (PR)
### 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:
```sh
git clone https://github.com/nuxt/ui.git
```
2. Enable [Corepack](https://github.com/nodejs/corepack):
```sh
corepack enable
```
3. Install dependencies:
```sh
pnpm install
```
4. Generate type stubs:
```sh
pnpm run dev:prepare
```
5. Configure your local development environment:
- To work on the **documentation** located in the `docs` folder, run:
```sh
pnpm run dev
```
- To test the components using **playground**, run:
```sh
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:
```json
{
"editor.codeActionsOnSave": {
"source.fixAll": false,
"source.fixAll.eslint": true
}
}
```
You can also use the `lint` command:
```sh
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:
```sh
pnpm run typecheck
```
### 3. Commit Conventions
We use [Conventional Commits](https://www.conventionalcommits.org/) for commit messages, which allows a changelog to be auto-generated based on the commits. Please read the [guide](https://www.conventionalcommits.org/en/v1.0.0/#summary) through if you aren't familiar with it already.
#### Note
- `fix` and `feat` are for actual code changes (that might affect logic). For typo or document changes, use `docs` or `chore` instead:
~~`fix: typo`~~ -> `docs: fix typo`
- If you are working on a specific component, ensure that you specify the main scope of your commit in brackets. e.g.
```
feat(Alert): new component
chore(Table): improve accessibility
```
### 4. Making a Pull Request
- Follow along the [instructions](https://github.com/nuxt/ui/blob/main/.github/PULL_REQUEST_TEMPLATE.md?plain=1) provided when creating a PR
- Ensure your PR's title adheres to the [Conventional Commits](https://www.conventionalcommits.org/) since it will be used once the code is merged.
- 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! ❤️

1
docs/content/1.getting-started/_dir.yml Normal file
View File

@@ -0,0 +1 @@
title: Getting Started