docs: migrate UI docs (#13245)
* docs: create a new UI docs project (#13233) * docs: create a new UI docs project * fix installation errors * docs: migrate UI docs content to new project (#13241) * Fix content * added examples for some components * finish adding examples * lint fix * fix build errors * delete empty files * path fixes + refactor * fix build error
This commit is contained in:
Shahed Nasser
@@ -0,0 +1,154 @@
|
||||
import Feedback from "@/components/Feedback"
|
||||
import { Note } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Install Medusa UI in Standalone Projects`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this guide, you'll learn how to install and use Medusa UI in a standalone project.
|
||||
|
||||
Medusa UI is a React UI library that, while intended for use within Medusa projects, can also be used in any React project.
|
||||
|
||||
<Note>
|
||||
|
||||
The icons package is installed independently from Medusa UI. Learn how to install it in the [Icons](../../icons/overview/page.mdx) guide.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Medusa UI Compatibility
|
||||
|
||||
To use Medusa UI in your standalone project, you must have:
|
||||
|
||||
- React 18+ installed. Most React-based frameworks and libraries, such as Next.js and Vite, are compatible with this requirement.
|
||||
- [Tailwind CSS](https://v3.tailwindcss.com/) installed. The components in Medusa UI are styled using Tailwind CSS, so you'll need to install it in your project as well.
|
||||
- Medusa UI was built with Tailwind CSS v3, but it may also support v4.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Install Medusa UI
|
||||
|
||||
In your standalone project, install the Medusa UI package with the following command:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/ui
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Install UI Presets
|
||||
|
||||
Medusa UI customizes Tailwind CSS classes to implement its design system, so you must also install the Medusa UI preset package.
|
||||
|
||||
To install the Medusa UI preset, run the following command:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install @medusajs/ui-preset --save-dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Configure Tailwind CSS
|
||||
|
||||
Next, you'll need to configure Tailwind CSS to use the Medusa UI preset and explicitly add the paths to the Medusa UI components as content files.
|
||||
|
||||
### Tailwind CSS v3 Configurations
|
||||
|
||||
In Tailwind CSS v3, which is the recommended version to use with Medusa UI, you need to add the following configurations to your `tailwind.config.js` or `tailwind.config.ts` file:
|
||||
|
||||
1. Add the Medusa UI preset to the `presets` array.
|
||||
2. Ensure that the `content` field includes the path to the Medusa UI package.
|
||||
|
||||
```js title="tailwind.config.js" highlights={[["5"]]}
|
||||
module.exports = {
|
||||
presets: [require("@medusajs/ui-preset")],
|
||||
content: [
|
||||
// ...
|
||||
"./node_modules/@medusajs/ui/dist/**/*.{js,jsx,ts,tsx}",
|
||||
],
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
If your project is in a monorepo, you'll need to resolve the path to the `@medusajs/ui` package from the monorepo root:
|
||||
|
||||
export const monorepoHighlights = [
|
||||
["3", "uiPath", "Resolve the UI package path from `node_modules`."],
|
||||
["13"]
|
||||
]
|
||||
|
||||
```tsx title="tailwind.config.js" highlights={monorepoHighlights}
|
||||
const path = require("path")
|
||||
|
||||
const uiPath = path.resolve(
|
||||
require.resolve("@medusajs/ui"),
|
||||
"../..",
|
||||
"\*_/_.{js,jsx,ts,tsx}"
|
||||
)
|
||||
|
||||
module.exports = {
|
||||
presets: [require("@medusajs/ui-preset")],
|
||||
content: [
|
||||
// ...
|
||||
uiPath,
|
||||
],
|
||||
// ...
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
### Tailwind CSS v4 Configurations
|
||||
|
||||
Medusa UI isn't officially compatible with Tailwind CSS v4 yet, so use it with caution.
|
||||
|
||||
In your CSS file that imports Tailwind CSS, add the following `@import`, `@config`, and `@source` directives:
|
||||
|
||||
```css
|
||||
@import "tailwindcss";
|
||||
@source "../node_modules/@medusajs/ui";
|
||||
@config "@medusajs/ui-preset";
|
||||
```
|
||||
|
||||
This will explicitly include the Medusa UI preset and its components in your Tailwind CSS build and apply the preset styles to your project.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Use Medusa UI in Standalone Projects
|
||||
|
||||
You can now start building your application with Medusa UI.
|
||||
|
||||
For example, you can use the `Button` in your custom components:
|
||||
|
||||
```tsx
|
||||
import { Button } from "@medusajs/ui"
|
||||
|
||||
export function ButtonDemo() {
|
||||
return <Button>Button</Button>
|
||||
}
|
||||
```
|
||||
|
||||
Refer to the documentation of each component to learn about its props and usage.
|
||||
|
||||
<Feedback title={"Install in Standalone Project"} />
|
||||
|
||||
---
|
||||
|
||||
## Update UI Packages in Standalone Projects
|
||||
|
||||
Medusa's design system packages, including `@medusajs/ui` and `@medusajs/ui-preset`, are versioned independently from other `@medusajs/*` packages. However, they're still released as part of Medusa's releases.
|
||||
|
||||
So, to find the latest updates and breaking changes to any of these packages, refer to the [release notes in the Medusa GitHub repository](https://github.com/medusajs/medusa/releases).
|
||||
|
||||
To update these packages in your standalone project, update their version in your `package.json` file and re-install dependencies. For example:
|
||||
|
||||
```json title="package.json"
|
||||
{
|
||||
"dependencies": {
|
||||
"@medusajs/ui": "4.0.0",
|
||||
"@medusajs/ui-preset": "4.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user