From db8fed61e72cf39268312c6b6ac7041b1d8eccbe Mon Sep 17 00:00:00 2001 From: zernonia Date: Mon, 18 Sep 2023 15:16:32 +0800 Subject: [PATCH] feat: installation section by framwork --- .../theme/components/LinkedCard.vue | 9 + .../theme/components/TableOfContent.vue | 3 + apps/www/.vitepress/theme/components/index.ts | 1 + apps/www/.vitepress/theme/config/docs.ts | 25 +++ apps/www/src/content/docs/cli.md | 5 +- apps/www/src/content/docs/installation.md | 186 +++++++----------- .../src/content/docs/installation/astro.md | 149 ++++++++++++++ .../src/content/docs/installation/laravel.md | 153 ++++++++++++++ .../www/src/content/docs/installation/nuxt.md | 116 +++++++++++ .../www/src/content/docs/installation/vite.md | 106 ++++++++++ 10 files changed, 640 insertions(+), 113 deletions(-) create mode 100644 apps/www/.vitepress/theme/components/LinkedCard.vue create mode 100644 apps/www/src/content/docs/installation/astro.md create mode 100644 apps/www/src/content/docs/installation/laravel.md create mode 100644 apps/www/src/content/docs/installation/nuxt.md create mode 100644 apps/www/src/content/docs/installation/vite.md diff --git a/apps/www/.vitepress/theme/components/LinkedCard.vue b/apps/www/.vitepress/theme/components/LinkedCard.vue new file mode 100644 index 00000000..791c75ab --- /dev/null +++ b/apps/www/.vitepress/theme/components/LinkedCard.vue @@ -0,0 +1,9 @@ + + + diff --git a/apps/www/.vitepress/theme/components/TableOfContent.vue b/apps/www/.vitepress/theme/components/TableOfContent.vue index b8064360..1c62ca15 100644 --- a/apps/www/.vitepress/theme/components/TableOfContent.vue +++ b/apps/www/.vitepress/theme/components/TableOfContent.vue @@ -42,6 +42,9 @@ function getHeadingsWithHierarchy(divId: string) { else if (level === 3 && currentLevel?.items) { currentLevel.items.push(item) } + else { + hierarchy.items.push(item) + } }) return hierarchy } diff --git a/apps/www/.vitepress/theme/components/index.ts b/apps/www/.vitepress/theme/components/index.ts index fff52ff0..49421ad1 100644 --- a/apps/www/.vitepress/theme/components/index.ts +++ b/apps/www/.vitepress/theme/components/index.ts @@ -1,5 +1,6 @@ export { default as ComponentPreview } from './ComponentPreview.vue' export { default as Callout } from './Callout.vue' +export { default as LinkedCard } from './LinkedCard.vue' export { default as ManualInstall } from './ManualInstall.vue' export { default as Steps } from './Steps.vue' export { default as VPImage } from './VPImage.vue' diff --git a/apps/www/.vitepress/theme/config/docs.ts b/apps/www/.vitepress/theme/config/docs.ts index 2905f907..9c6d2c53 100644 --- a/apps/www/.vitepress/theme/config/docs.ts +++ b/apps/www/.vitepress/theme/config/docs.ts @@ -95,6 +95,31 @@ export const docsConfig: DocsConfig = { }, ], }, + { + title: 'Installation', + items: [ + { + title: 'Vite', + href: '/docs/installation/vite', + items: [], + }, + { + title: 'Nuxt', + href: '/docs/installation/nuxt', + items: [], + }, + // { + // title: 'Astro', + // href: '/docs/installation/astro', + // items: [], + // }, + { + title: 'Laravel', + href: '/docs/installation/laravel', + items: [], + }, + ], + }, { title: 'Components', items: [ diff --git a/apps/www/src/content/docs/cli.md b/apps/www/src/content/docs/cli.md index 5441bc3e..40c00ea3 100644 --- a/apps/www/src/content/docs/cli.md +++ b/apps/www/src/content/docs/cli.md @@ -17,15 +17,14 @@ You will be asked a few questions to configure `components.json`: ```txt:line-numbers Would you like to use TypeScript (recommended)? no / yes -Which framework are you using? Vite + Vue / Nuxt +Which framework are you using? Vite / Nuxt / Laravel Which style would you like to use? › Default Which color would you like to use as base color? › Slate Where is your global CSS file? › › src/index.css Do you want to use CSS variables for colors? › no / yes Where is your tailwind.config.js located? › tailwind.config.js Configure the import alias for components: › @/components -Configure the import alias for utils: › @/lib/utils -Are you using React Server Components? › no / yes (no) +Configure the import alias for utils: › @/lib/utils ``` ### Options diff --git a/apps/www/src/content/docs/installation.md b/apps/www/src/content/docs/installation.md index 336e2bf1..34a10e93 100644 --- a/apps/www/src/content/docs/installation.md +++ b/apps/www/src/content/docs/installation.md @@ -2,128 +2,94 @@ title: Installation description: How to install dependencies and structure your app. --- - - - -Unlike the original [shadcn/ui](https://ui.shadcn.com) for React, where the full components can exist in a single file, components in this port are split into multiple files due to majority vote from [Vue community](https://twitter.com/zernonia/status/1694351679540580524) to use `SFC` rather than `h()` render function or `JSX`, so utilizing the CLI to add components will be the optimal approach. - +## Frameworks -The CLI will create a folder for _each_ component, which will sometimes just contain a single Vue file, and in other times, multiple files. Within each folder, there will be an `index.ts` file that exports the component(s), so you can import them from a single file. +
+ + + Vite + + +

Vite

+ + + + Nuxt + + +

Nuxt

+ + + + + + +

Laravel

+ +
-For example, the Accordion component is split into four `.vue` files: -- `Accordion.vue` -- `AccordionContent.vue` -- `AccordionItem.vue` -- `AccordionTrigger.vue` -They can then be imported from the `accordion/index.ts` file like so: +## TypeScript -```ts -import * as Accordion from '@/components/ui/accordion' +This project and the components are written in TypeScript. We recommend using TypeScript for your project as well. -// or -import { - Accordion, - AccordionContent, - AccordionItem, - AccordionTrigger -} from '@/components/ui/accordion' -``` +However we provide a JavaScript version of the components as well. The JavaScript version is available via the [cli](/docs/cli). -Regardless of the import approach you take, the components will be tree-shaken by Rollup, so you don't have to worry about unused components being bundled into your app. +To opt-out of TypeScript, you can use the `tsx` flag in your `components.json` file. -## New Project - - - -### Create project - -Use the Vue CLI to create a new project. - -```bash -npm create vue@latest -``` - -### Add Tailwind and its configuration - -Install `tailwindcss` and its peer dependencies, then generate your `tailwind.config.js` and `postcss.config.js` files: - -```bash -npm install -D tailwindcss postcss autoprefixer - -npx tailwindcss init -p -``` - -### Install dependencies - -```bash -npm install -``` - -### Run the CLI - -```bash -npx shadcn-vue@latest init -``` - -### Configure components.json - -You will be asked a few questions to configure `components.json`: - -```txt:line-numbers -Would you like to use TypeScript (recommended)? no / yes -Which framework are you using? Vite + Vue / Nuxt -Which style would you like to use? › Default -Which color would you like to use as base color? › Slate -Where is your global CSS file? › › src/index.css -Do you want to use CSS variables for colors? › no / yes -Where is your tailwind.config.js located? › tailwind.config.js -Configure the import alias for components: › @/components -Configure the import alias for utils: › @/lib/utils -Are you using React Server Components? › no / yes (no) -``` - -### Edit tsconfig.json - -By default your `tsconfig.json` for new project should be configured nicely. However, make sure the code below is added in the compilerOptions of your tsconfig.json so your app can resolve paths without error - -```json +```json {10} title="components.json" { - "compilerOptions": { - "baseUrl": ".", - "paths": { - "@/*": ["./src/*"] - } + "style": "default", + "tailwind": { + "config": "tailwind.config.js", + "css": "src/app/globals.css", + "baseColor": "zinc", + "cssVariables": true + }, + "typescript": false, + "aliases": { + "utils": "~/lib/utils", + "components": "~/components" } } ``` +To configure import aliases, you can use the following `jsconfig.json`: -### That's it - -You can now start adding components to your project. - -```bash -npx shadcn-vue@latest add button -``` - -The command above will add the `Button` component to your project. You can then import it like this: - -```vue {2,7} - - - -``` - - - \ No newline at end of file +```json {4} title="jsconfig.json" +{ + "compilerOptions": { + "paths": { + "@/*": ["./*"] + } + } +} \ No newline at end of file diff --git a/apps/www/src/content/docs/installation/astro.md b/apps/www/src/content/docs/installation/astro.md new file mode 100644 index 00000000..603236c4 --- /dev/null +++ b/apps/www/src/content/docs/installation/astro.md @@ -0,0 +1,149 @@ +--- +title: Astro +description: Install and configure Astro. +--- + + + +### Create project + +Start by creating a new Astro project: + +```bash +npm create astro@latest +``` + +### Configure your Astro project + +You will be asked a few questions to configure your project: + +```txt showLineNumbers +- Where should we create your new project? +./your-app-name +- How would you like to start your new project? +Choose a starter template (or Empty) +- Install dependencies? +Yes +- Do you plan to write TypeScript? +Yes +- How strict should TypeScript be? +Strict +- Initialize a new git repository? (optional) +Yes/No +``` + +### Add React to your project + +Install React using the Astro CLI: + +```bash +npx astro add react +``` + + + +Answer `Yes` to all the question prompted by the CLI when installing React. + + + +### Add Tailwind CSS to your project + +Install Tailwind CSS using the Astro CLI: + +```bash +npx astro add tailwind +``` + + + +Answer `Yes` to all the question prompted by the CLI when installing Tailwind CSS. + + + +### Edit tsconfig.json file + +Add the code below to the tsconfig.json file to resolve paths: + +```json {2-7} showLineNumbers +{ + "compilerOptions": { + "baseUrl": ".", + "paths": { + "@/*": ["src/*"] + } + } +} +``` + +### Run the CLI + +Run the `shadcn-ui` init command to setup your project: + +```bash +npx shadcn-ui@latest init +``` + +### Configure components.json + +You will be asked a few questions to configure `components.json`: + +```txt showLineNumbers +Would you like to use TypeScript (recommended)? no / yes +Which style would you like to use? › Default +Which color would you like to use as base color? › Slate +Where is your global CSS file? › › ./src/styles/globals.css +Do you want to use CSS variables for colors? › no / yes +Where is your tailwind.config.js located? › tailwind.config.cjs +Configure the import alias for components: › @/components +Configure the import alias for utils: › @/lib/utils +Are you using React Server Components? › no +``` + +### Import the globals.css file + +Import the `globals.css` file in the `src/index.astro` file: + +```ts {2} showLineNumbers +import '@/styles/globals.css' +``` + +### Update astro tailwind config + +To prevent serving the Tailwind base styles twice, we need to tell Astro not to apply the base styles, since we already include them in our own `globals.css` file. To do this, set the `applyBaseStyles` config option for the tailwind plugin in `astro.config.mjs` to `false`. + +```ts {3-5} showLineNumbers +export default defineConfig({ + integrations: [ + tailwind({ + applyBaseStyles: false, + }), + ], +}) +``` + +### That's it + +You can now start adding components to your project. + +```bash +npx shadcn-ui@latest add button +``` + +The command above will add the `Button` component to your project. You can then import it like this: + +```astro {2,10} showLineNumbers +--- +import { Button } from "@/components/ui/button" +--- + + + + Astro + + + + + +``` + + \ No newline at end of file diff --git a/apps/www/src/content/docs/installation/laravel.md b/apps/www/src/content/docs/installation/laravel.md new file mode 100644 index 00000000..538b1e0e --- /dev/null +++ b/apps/www/src/content/docs/installation/laravel.md @@ -0,0 +1,153 @@ +--- +title: Laravel +description: Install and configure Laravel with Inertia +--- + + + +### Create project + +Start by creating a new Laravel project with Inertia and Vue using the laravel installer `laravel new my-app`: + +```bash +laravel new my-app --typescript --breeze --stack=vue --git --no-interaction +``` + +### Run the CLI + +Run the `shadcn-vue` init command to setup your project: + +```bash +npx shadcn-vue@latest init +``` + +### Configure components.json + +You will be asked a few questions to configure `components.json`: + +```txt showLineNumbers +Would you like to use TypeScript (recommended)? no / yes +Which framework are you using? Vite / Nuxt / Laravel +Which style would you like to use? › Default +Which color would you like to use as base color? › Slate +Where is your global CSS file? › › src/index.css +Do you want to use CSS variables for colors? › no / yes +Where is your tailwind.config.js located? › tailwind.config.js +Configure the import alias for components: › @/components +Configure the import alias for utils: › @/lib/utils +``` + +### Update tailwind.config.js + +The `shadcn-vue` CLI will automatically overwrite your `tailwind.config.js`. Update it to look like this: + +```js +import forms from '@tailwindcss/forms' +import defaultTheme from 'tailwindcss/defaultTheme' + +/** @type {import('tailwindcss').Config} */ +export default { + darkMode: 'class', + content: [ + './vendor/laravel/framework/src/Illuminate/Pagination/resources/views/*.blade.php', + './storage/framework/views/*.php', + './resources/views/**/*.blade.php', + './resources/js/**/*.tsx', + ], + + theme: { + container: { + center: true, + padding: '2rem', + screens: { + '2xl': '1400px', + }, + }, + extend: { + colors: { + border: 'hsl(var(--border))', + input: 'hsl(var(--input))', + ring: 'hsl(var(--ring))', + background: 'hsl(var(--background))', + foreground: 'hsl(var(--foreground))', + primary: { + DEFAULT: 'hsl(var(--primary))', + foreground: 'hsl(var(--primary-foreground))', + }, + secondary: { + DEFAULT: 'hsl(var(--secondary))', + foreground: 'hsl(var(--secondary-foreground))', + }, + destructive: { + DEFAULT: 'hsl(var(--destructive))', + foreground: 'hsl(var(--destructive-foreground))', + }, + muted: { + DEFAULT: 'hsl(var(--muted))', + foreground: 'hsl(var(--muted-foreground))', + }, + accent: { + DEFAULT: 'hsl(var(--accent))', + foreground: 'hsl(var(--accent-foreground))', + }, + popover: { + DEFAULT: 'hsl(var(--popover))', + foreground: 'hsl(var(--popover-foreground))', + }, + card: { + DEFAULT: 'hsl(var(--card))', + foreground: 'hsl(var(--card-foreground))', + }, + }, + borderRadius: { + lg: 'var(--radius)', + md: 'calc(var(--radius) - 2px)', + sm: 'calc(var(--radius) - 4px)', + }, + fontFamily: { + sans: ['Figtree', ...defaultTheme.fontFamily.sans], + }, + keyframes: { + 'accordion-down': { + from: { height: 0 }, + to: { height: 'var(--radix-accordion-content-height)' }, + }, + 'accordion-up': { + from: { height: 'var(--radix-accordion-content-height)' }, + to: { height: 0 }, + }, + }, + animation: { + 'accordion-down': 'accordion-down 0.2s ease-out', + 'accordion-up': 'accordion-up 0.2s ease-out', + }, + }, + }, + + plugins: [forms, require('tailwindcss-animate')], +} +``` + +### That's it + +You can now start adding components to your project. + +```bash +npx shadcn-vue@latest add button +``` + +The command above will add the `Button` component to your project. You can then import it like this: + +```vue {2,7} + + + +``` + + \ No newline at end of file diff --git a/apps/www/src/content/docs/installation/nuxt.md b/apps/www/src/content/docs/installation/nuxt.md new file mode 100644 index 00000000..1200e635 --- /dev/null +++ b/apps/www/src/content/docs/installation/nuxt.md @@ -0,0 +1,116 @@ +--- +title: Nuxt +description: Install and configure Nuxt. +--- + + + +### Create project + +Start by creating a new Nuxt project using `create-next-app`: + +```bash +npx nuxi@latest init my-app +``` + +### Install TailwindCSS module + +```bash +npm install -D @nuxtjs/tailwindcss +``` + +```ts +export default defineNuxtConfig({ + modules: ['@nuxtjs/tailwindcss'] +}) +``` + + +### Run the CLI + +Run the `shadcn-vue` init command to setup your project: + +```bash +npx shadcn-vue@latest init +``` + +### Configure components.json + +You will be asked a few questions to configure `components.json`: + +```txt showLineNumbers +Would you like to use TypeScript (recommended)? no / yes +Which framework are you using? Vite / Nuxt / Laravel +Which style would you like to use? › Default +Which color would you like to use as base color? › Slate +Where is your global CSS file? › › src/index.css +Do you want to use CSS variables for colors? › no / yes +Where is your tailwind.config.js located? › tailwind.config.js +Configure the import alias for components: › @/components +Configure the import alias for utils: › @/lib/utils +``` + +### App structure + +Here's the default structure of Nuxt app. You can use this as a reference: + +```txt {6-16,20-21} +. +├── pages +│ ├── index.vue +│ └── dashboard.vue +├── components +│ ├── ui +│ │ ├── alert-dialog +│ │ │ ├── AlertDialog.vue +│ │ │ └── ... +│ │ ├── button +│ │ │ ├── Button.vue +│ │ │ └── ... +│ │ ├── dropdown-menu +│ │ │ ├── Dropdown.vue +│ │ │ └── ... +│ │ └── ... +│ ├── MainNav.vue +│ ├── PageHeader.vue +│ └── ... +├── lib +│ └── utils.ts +├── assets +│ ├── css +│ │ └── tailwind.css +├── app.vue +├── nuxt.config.ts +├── package.json +├── tailwind.config.js +└── tsconfig.json +``` + +- I place the UI components in the `components/ui` folder. +- The rest of the components such as `` and `` are placed in the `components` folder. +- The `lib` folder contains all the utility functions. I have a `utils.ts` where I define the `cn` helper. +- The `styles` folder contains the global CSS. + +### That's it + +You can now start adding components to your project. + +```bash +npx shadcn-vue@latest add button +``` + +The command above will add the `Button` component to your project. You can then import it like this: + +```vue {2,7} + + + +``` + + \ No newline at end of file diff --git a/apps/www/src/content/docs/installation/vite.md b/apps/www/src/content/docs/installation/vite.md new file mode 100644 index 00000000..68aa1088 --- /dev/null +++ b/apps/www/src/content/docs/installation/vite.md @@ -0,0 +1,106 @@ +--- +title: Vite +description: Install and configure Vite. +--- + + + +### Create project + +Start by creating a new Vue project using `vite`: + +```bash +# npm 6.x +npm create vite@latest my-vue-app --template vue + +# npm 7+, extra double-dash is needed: +npm create vite@latest my-vue-app -- --template vue +``` + +### Add Tailwind and its configuration + +Install `tailwindcss` and its peer dependencies, then generate your `tailwind.config.js` and `postcss.config.js` files: + +```bash +npm install -D tailwindcss postcss autoprefixer + +npx tailwindcss init -p +``` + +### Edit tsconfig.json + +Add the code below to the compilerOptions of your tsconfig.json so your app can resolve paths without error + +```typescript +"baseUrl": ".", +"paths": { + "@/*": ["./src/*"] +} +``` + +### Update vite.config.ts + +Add the code below to the vite.config.ts so your app can resolve paths without error + +```typescript +import path from "path" +import vue from "@vitejs/plugin-vue" +import { defineConfig } from "vite" + +export default defineConfig({ + plugins: [vue()], + resolve: { + alias: { + "@": path.resolve(__dirname, "./src"), + }, + }, +}) +``` + +### Run the CLI + +Run the `shadcn-vue` init command to setup your project: + +```bash +npx shadcn-vue@latest init +``` + +### Configure components.json + +You will be asked a few questions to configure `components.json`: + +```txt showLineNumbers +Would you like to use TypeScript (recommended)? no / yes +Which framework are you using? Vite / Nuxt / Laravel +Which style would you like to use? › Default +Which color would you like to use as base color? › Slate +Where is your global CSS file? › › src/index.css +Do you want to use CSS variables for colors? › no / yes +Where is your tailwind.config.js located? › tailwind.config.js +Configure the import alias for components: › @/components +Configure the import alias for utils: › @/lib/utils +``` + +### That's it + +You can now start adding components to your project. + +```bash +npx shadcn-vue@latest add button +``` + +The command above will add the `Button` component to your project. You can then import it like this: + +```vue {2,7} + + + +``` + + \ No newline at end of file