From 3f0b24229633f3de397d5fc936fc56c48fc53b56 Mon Sep 17 00:00:00 2001 From: Damir Vazgird Date: Thu, 1 Feb 2024 21:05:28 -0800 Subject: [PATCH] add usage docs to readme --- README.md | 247 ++++++++++++++++++++++++++++++++++++++++++++++----- package.json | 3 +- yarn.lock | 20 ++--- 3 files changed, 231 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index d2ff1e4..9347ef6 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,213 @@ A React UI component library bundled with Rollup.js to commonJs, ES6 Modules, St This project is a clone of [Shared](https://github.com/behzadam/shared) and has been updated for personal use. -## Getting started +## Usage + +This section will cover how to use the library in your own project. + +### Peer Dependencies + +To use this package and all of it's components without any issues, you will need to install some dependencies for everything to work as intended. + +The reason these are required is because most of these components are created using shadcn/ui cli, which integrates radix-ui with tailwind. And these two libraries have some dependencies that are necessary for the ui to function and render like its supposed. + +Here's a list of all the peer dependencies this package relies on: + +- `class-variance-authority@^0.7.0` +- `clsx@^2.1.0` +- `lucide-react@0.312.0` +- `react@^18.2.0` +- `react-dom@^18.2.0"` +- `react-hook-form@^7.49.3` +- `tailwind-merge@^2.2.0` +- `tailwindcss-animate@^1.0.7` +- `tailwindcss@^3.4.1` + +### Installing Dependencies + +You can use whatever package management library, but I'll be using yarn for this example. + +1. Install the package as a dependency + +``` +yarn add chad-ui +``` + +2. Install other necessary dependencies: + +``` +yarn add class-variance-authority clsx lucide-react react react-dom react-hook-form tailwind-merge +``` + +These should be added as dev dependencies: + +``` +yarn add -D tailwindcss-animate tailwindcss +``` + +### Configuring Tailwind + +You will need to configure tailwind with chad-ui to be able to use the ui components without any issues. If you don't know how to do that and need a good starting point, look for a popular React 18 and TailwindCSS boilerplate or starter. + +While testing the library in development, I used this: [ReactJS Vite TailwindCSS Boilerplate](https://github.com/joaopaulomoraes/reactjs-vite-tailwindcss-boilerplate), and had no issues. Now, then to configure tailwind with chad-ui: + +1. Create or update your tailwind.config.js file in the root of your project's dir. + +``` +import defaultConfig from 'chad-ui/tailwind.config' + +export default { + ...defaultConfig, + content: [ + './node_modules/chad-ui/**/*.{mjs,js,ts,jsx,tsx}', + './src/**/*.{mjs,js,ts,jsx,tsx}' + ], + theme: { + extend: { + ...defaultConfig.theme.extend + } + }, + plugins: [...defaultConfig.plugins] +} +``` + +2. Create or update your main stylesheet + +``` +@import 'chad-ui/dist/styles/tailwind.css'; + +:root { + --primary: 83 100% 50%; + --primary-foreground: 54 50% 3%; +} + +.dark { + --primary: 54 50% 3%; + --primary-foreground: 83 100% 50%; +} + +``` + +3. Import your tailwind styles + +Inside of `src/index.tsx`, add an import to your stylesheet: + +``` +import 'styles/main.css' +``` + +4. Use your Chad-UI components + +Inside of `src/components/App.tsx`, import the Button component: + +``` +import { Button } from 'chad-ui' +``` + +Try adding a button around a link, using the `asChild` prop to render your link in the style of a button: + +``` +Button asChild size="lg"> + Start building for free + +``` + +### Themes + +Chad-UI uses [HSL to define themes with css vars](https://www.smashingmagazine.com/2021/07/hsl-colors-css/). The themes stylesheet looks like this: + +``` +:root { + --background: 0 0% 100%; + --foreground: 0 0% 3.9%; + + --card: 0 0% 100%; + --card-foreground: 0 0% 3.9%; + + --popover: 0 0% 100%; + --popover-foreground: 0 0% 3.9%; + + --primary: 0 0% 9%; + --primary-foreground: 0 0% 98%; + + --secondary: 0 0% 96.1%; + --secondary-foreground: 0 0% 9%; + + --muted: 0 0% 96.1%; + --muted-foreground: 0 0% 45.1%; + + --accent: 0 0% 96.1%; + --accent-foreground: 0 0% 9%; + + --destructive: 0 84.2% 60.2%; + --destructive-foreground: 0 0% 98%; + + --border: 0 0% 89.8%; + --input: 0 0% 89.8%; + --ring: 0 0% 3.9%; + + --radius: 0.5rem; +} + +.dark { + --background: 0 0% 3.9%; + --foreground: 0 0% 98%; + + --card: 0 0% 3.9%; + --card-foreground: 0 0% 98%; + + --popover: 0 0% 3.9%; + --popover-foreground: 0 0% 98%; + + --primary: 0 0% 98%; + --primary-foreground: 0 0% 9%; + + --secondary: 0 0% 14.9%; + --secondary-foreground: 0 0% 98%; + + --muted: 0 0% 14.9%; + --muted-foreground: 0 0% 63.9%; + + --accent: 0 0% 14.9%; + --accent-foreground: 0 0% 98%; + + --destructive: 0 62.8% 30.6%; + --destructive-foreground: 0 0% 98%; + + --border: 0 0% 14.9%; + --input: 0 0% 14.9%; + --ring: 0 0% 83.1%; +} +``` + +You can also import it into your own stylesheet like this: + +``` +@import 'chad-ui/dist/styles/themes.css'; + +``` + +### Globals + +``` +@layer base { + * { + @apply border-border; + } + + body { + @apply bg-background text-foreground; + } +} +``` + +--- + +## Development + +Chad-UI is open-source so feel free to contribute. The following is documentation on how to setup a dev environment and other information necessary to properly become a contributor. + +### Getting started ``` git clone git@github.com:dvzrd/react-ui.git @@ -12,7 +218,7 @@ cd react-ui yarn ``` -## Developing +### Local Dev To start the developing run: @@ -25,9 +231,9 @@ To open Storybook manually open your Browser and navigate to [http://localhost:6 Start developing your components in `src/components` folder and update the `src/index.js` file accordingly. Always provide an `YourComponent.stories.tsx` file, so your component will show up in Storybook. -## Linting and Code formating for Typescript +### Linting and Code formatting for Typescript -Linting and code formating is done via [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) using [eslint-plugin-react](https://www.npmjs.com/package/eslint-plugin-react) and +Linting and code formatting is done via [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/) using [eslint-plugin-react](https://www.npmjs.com/package/eslint-plugin-react) and [eslint-config-prettier](https://github.com/prettier/eslint-config-prettier). You can modify linting rules by overriding them in the `.eslintrc.cjs` file. @@ -41,7 +247,7 @@ or (if automatic fixing is possible) yarn lint:fix ``` -## Testing +### Testing Testing is done with [Vitest](https://vitest.dev/) and [@testing-library/react](https://testing-library.com/docs/react-testing-library/intro/) @@ -49,7 +255,7 @@ Testing is done with [Vitest](https://vitest.dev/) and [@testing-library/react]( yarn test ``` -## Publishing your library to NPM +### Publishing your library to NPM To release your library to NPM or your private Registry, make sure you have an active account at [NPM](https://www.npmjs.com/), your `.npmrc` file is correctly setup and the registry url at publishConfig in `package.json` file is set to your repository url, then: @@ -57,62 +263,59 @@ To release your library to NPM or your private Registry, make sure you have an a yarn release ``` -## Storybook +### Storybook For custom layouts, styling and more information about Storybook, please refer to [Storybook](https://storybook.js.org/basics/writing-stories/) documentation. #### Deploy Storybook to GitHub Pages -Make sure the homepage url in `package.json` file is set to your githup pages url, then: +Make sure the homepage url in `package.json` file is set to your github pages url, then: ``` yarn deploy ``` -## Scripts +### Scripts - `yarn start` : Only serves Storybook. +- `yarn upgrade`: Upgrade dependencies using yarn upgrade-interactive script - `yarn build` : Builds your library (build can be found in `dist` folder). -- `yarn storybook:build` : Builds the static Storybook in case you want to deploy it. -- `yarn test` : Runs the tests. -- `yarn test:coverage`: Runs the test and shows the coverage. +- `yarn deploy` : Deploys storybook to github pages. - `yarn lint` : Runs the linter, Typescript typecheck and stylelint. - `yarn lint:fix` : Runs the linter, Typescript typecheck and stylelint and fixes automatic fixable issues. - `yarn eslint`: Runs only the JavaScript linter. - `yarn eslint:fix`: Runs only the JavaScript linter and fixes automatic fixable issues. -- `yarn stylelint`: Runs only the style linter. -- `yarn stylelint:fix`: Runs only the style linter and fixes automatic fixable issues. - `yarn check-types`: Runs typescript type checker. - `yarn check-types:pretty`: Runs typescript type checker with pretty responses. - `yarn ci`: Runs Linting, tests and type checker all together. +- `yarn test` : Runs the tests. - `yarn release` : Publishes your Library on NPM or your private Registry (depending on your config in your `.npmrc` file). - `yarn storybook`: Same as yarn start, to serve storybook. - `yarn storybook:build`: Generates the build for storybook in `storybook-static` folder, that can be deployed wherever you need. - `yarn storybook:deploy`: Builds and deploys Storybook to GitHub Pages.' - `yarn ui:diff`: Check for updates against the latest shadcn-ui registry. -- `yarn upgrade`: Upgrade dependencies using yarn upgrade-interactive script -## Resources +### Resources -### Bundler +#### Bundler - [Rollup.js](https://rollupjs.org/guide/en) -### Code Formatter +#### Code Formatter - [Prettier](https://prettier.io/) -### Storybook +#### Storybook - [Storybook](https://storybook.js.org/) -### Testing +#### Testing - [Vitest](https://vitest.dev/) - [@testing-library/react](https://testing-library.com/docs/react-testing-library/intro/) - [@testing-library/jest-dom](https://github.com/testing-library/jest-dom) -### Linting +#### Linting - [ESLint](https://eslint.org/) - [eslint-plugin-react](https://www.npmjs.com/package/eslint-plugin-react) @@ -120,6 +323,6 @@ yarn deploy - [stylelint-prettier](https://github.com/prettier/stylelint-prettier) - [stylelint-scss](https://github.com/kristerkari/stylelint-scss) -### Compiler +#### Compiler - [Typescript](https://www.typescriptlang.org/) diff --git a/package.json b/package.json index 7689a58..250e018 100644 --- a/package.json +++ b/package.json @@ -85,7 +85,7 @@ "@storybook/testing-library": "^0.2.2", "@svgr/rollup": "^8.1.0", "@testing-library/jest-dom": "^6.4.1", - "@testing-library/react": "^14.2.0", + "@testing-library/react": "^14.2.1", "@testing-library/user-event": "^14.5.2", "@types/node": "^20.11.16", "@types/react": "^18.2.51", @@ -110,7 +110,6 @@ "jsdom": "^24.0.0", "lucide-react": "^0.321.0", "postcss": "^8.4.33", - "postcss-scss": "^4.0.9", "prettier": "3.2.4", "react": "^18.2.0", "react-dom": "^18.2.0", diff --git a/yarn.lock b/yarn.lock index 52b9859..c567c9c 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5002,9 +5002,9 @@ __metadata: languageName: node linkType: hard -"@testing-library/react@npm:^14.2.0": - version: 14.2.0 - resolution: "@testing-library/react@npm:14.2.0" +"@testing-library/react@npm:^14.2.1": + version: 14.2.1 + resolution: "@testing-library/react@npm:14.2.1" dependencies: "@babel/runtime": ^7.12.5 "@testing-library/dom": ^9.0.0 @@ -5012,7 +5012,7 @@ __metadata: peerDependencies: react: ^18.0.0 react-dom: ^18.0.0 - checksum: c7fa471dbb01c8bcf66abbdb210b24fb36c81afcc99db3ea4e22bd1556af1ccbd2a9dd2b14bd86870690f681c3e72080468728d63084e73bef071062d4174c1c + checksum: 7054ae69a0e06c0777da8105fa08fac7e8dac570476a065285d7b993947acda5c948598764a203ebaac759c161c562d6712f19f5bd08be3f09a07e23baee5426 languageName: node linkType: hard @@ -6639,7 +6639,7 @@ __metadata: "@storybook/testing-library": ^0.2.2 "@svgr/rollup": ^8.1.0 "@testing-library/jest-dom": ^6.4.1 - "@testing-library/react": ^14.2.0 + "@testing-library/react": ^14.2.1 "@testing-library/user-event": ^14.5.2 "@types/node": ^20.11.16 "@types/react": ^18.2.51 @@ -6664,7 +6664,6 @@ __metadata: jsdom: ^24.0.0 lucide-react: ^0.321.0 postcss: ^8.4.33 - postcss-scss: ^4.0.9 prettier: 3.2.4 react: ^18.2.0 react-dom: ^18.2.0 @@ -12379,15 +12378,6 @@ __metadata: languageName: node linkType: hard -"postcss-scss@npm:^4.0.9": - version: 4.0.9 - resolution: "postcss-scss@npm:4.0.9" - peerDependencies: - postcss: ^8.4.29 - checksum: dc358bafc23d52ed3a9a29333808825deba213042be74ece6eae7a61c692f67d0e6691fa7005367b013c01c79562fbb9ef2fe4c0485075233931bd90715f5132 - languageName: node - linkType: hard - "postcss-selector-parser@npm:^6.0.11, postcss-selector-parser@npm:^6.0.2, postcss-selector-parser@npm:^6.0.4, postcss-selector-parser@npm:^6.0.5, postcss-selector-parser@npm:^6.0.9": version: 6.0.15 resolution: "postcss-selector-parser@npm:6.0.15"