@televet/kibble-ui 0.1.0-beta.21 → 0.1.0-beta.3

package/README.md

@@ -8,17 +8,16 @@ https://televet.github.io/kibble-ui/
 
 ### New Project Setup
 
-If your project does not include a `.npmrc`, create it and add the following:
+If your project does not include a .npmrc, create it and add the following:
 
 `//registry.npmjs.org/:_authToken=${NPM_TOKEN}`
 
-Then add the NPM_TOKEN environment variable to your .bash_profile or .zshrc
+#### Add NPM_TOKEN environment variable
 
-`export NPM_TOKEN=${SOME_TOKEN}`
+In your .bash_profile or .zshrc
+`export NPM_TOKEN=SOME_TOKEN`
 
-Note: The NPM token can be found here in our [shared accounts table](https://www.notion.so/televet/Shared-Accounts-c691ae4e0dc8482c876aa0f4a56d8ea7)
-
-### Install in project
+#### Install in project
 
 `npm i --save @televet/kibble-ui`
 
@@ -31,49 +30,41 @@ import {
 } from 'kibble-ui';
 ```
 
-## Development Setup
-
-### Linking Projects for Local Development
+### Development Setup
 
-```
-$ cd kibble-ui           # navigate into the package directory
-$ rm -rf node_modules    # remove existing node_modules
-$ npm run build          # ensure there are build files available for the package to reference
+`$ npm i` - Install dependencies.  
+`npm run start` runs CRA in development mode with hot reloading. Open http://localhost:3000 to see your code live.
 
-# Update your library's package.json so that react and react-dom are pointing to your projects node_modules versions of these two packages. See reference to mutliple versions of react error here for more info on why this is necessary: https://reactjs.org/warnings/invalid-hook-call-warning.html#duplicate-react
+#### Linking Projects for Local Development
 
-# "react": "../clinic-web/node_modules/react"
-# "react-dom": "../clinic-web/node_modules/react-dom"
+```
+cd ~/kibble-ui                              # go into the package directory
+npm run build                               # ensure there are build files available for the package to reference
+npm link ../clinic-web/node_modules/react   # links kibble-ui react to clinic-web react to prevent two versions of react. See reference to this error here: https://reactjs.org/warnings/invalid-hook-call-warning.html#duplicate-react
 
-$ npm i                  # install packages
-$ npm run start          # start the development server
+# You may need to run the link commands using sudo if you get a permissions error
 
-# Navigate to project directory and update package.json to point to your local copy of your library
+# Navigate to project directory and update package.json to point to your local copy of kibble-ui
 # "@televet/kibble-ui": "./../kibble-ui"
 
-$ cd clinic-web          # go into a project directory
-$ rm -rf node_modules    # remove existing node_modules
-$ npm install            # fresh install with local version of kibble ui
-$ npm run start          # start the development server
+cd ~/clinic-web                             # go into a project directory
+npm install                                 # fresh install without kibble ui
 
-# When linking local packages like this your text editor may display errors saying the package cannot be found, however, if you restart your editor these errors should dissapear.
+# To see what links you've created globally you can run the following command
+npm list -g
+
+# To see what links an individual project is currently using run the following command from within that projects root folder
+npm list -link
 ```
 
-### Unlinking Projects after Local Development is Complete
+#### Unlinking Projects after Local Development is Complete
 
 ```
-# Inside of library
-$ git checkout package.json
-$ rm -rf node_modules
-$ npm install
-
-# Inside of project
-$ git checkout package.json
-$ rm -rf node_modules
-$ npm install
+# remove link to local files
+npm install --save @televet/kibble-ui   # re-install published project
 ```
 
-### `src` directory structure
+#### `src` directory structure
 
 Development takes place inside `src` directory. This is where your library code should live, this code will be bundled with rollup and published to NPM. Exports from `src/index.js` will be included in the library. Files with the `.stories.*` extension will be compiled and built to the `docs` folder and deployed with github pages.
 
@@ -111,9 +102,10 @@ Development takes place inside `src` directory. This is where your library code
 
 ## Build
 
-This site uses [Storybook](https://storybook.js.org/) configuration to handle documentation and examples.
+Template has [Storybook](https://storybook.js.org/) configuration to handle documentation and examples.
 
 ```bash
+npm run start # starts Storybook in development mode, http://localhost:6006/
 npm run build # bundles library code to `build` folder, and documentation code to `docs` folder in the root of project.
 ```
 
@@ -121,7 +113,7 @@ You can view live documentation here after deploying: https://televet.github.io/
 
 ## Deploy and Publish
 
-1. Update npm version number with `npm version <patch, major, or minor>`. Read more about [the version options](https://docs.npmjs.com/updating-your-published-package-version-number) here.
+1. Update npm version number with [one of these commands](https://docs.npmjs.com/updating-your-published-package-version-number).
 2. Run `npm run build`
 3. Commit changes to git.
 4. When pushing to master, GitHub will publish the package to npm with latest changes.
@@ -183,6 +175,207 @@ Template includes [stylelint](https://stylelint.io/), to check CSS/SASS/LESS fil
 
 Stylelint errors don't prevent build of application in development mode.
 
+## Style options
+
+### CSS modules
+
+Template uses vanilla CSS with `autoprefixer` enabled. To avoid classname collisions and reduce nesting we are using `css-modules`. To make css-modules work, stylesheet file name should have `.module` suffix.
+
+```jsx
+import React from 'react';
+import classes from './Component.module.css';
+
+const Component = () => <div className={classes.wrapper}>Component</div>;
+```
+
+### Add SASS/SCSS
+
+SASS/SCSS support comes "out of the box" in CRA. To enable it:
+
+1. Install `node-sass`
+
+   ```shell script
+   yarn add node-sass gatsby-plugin-sass --dev
+   ```
+
+2. Change `.lintstagedrc` to lint `scss` files instead of `css`.
+
+   ```json
+   {
+     "*.js": ["eslint --fix"],
+     "*.scss": ["stylelint --fix"]
+   }
+   ```
+
+3. Change `rollup.config.js` to support `scss` files:
+
+```js
+postcss({
+  extract: process.env.REACT_APP_PKG_STYLE || pkg.style,
+  inline: false,
+  plugins: postcssPlugins,
+  extensions: ['scss'], // <=== here
+}),
+```
+
+4. Add scss support to Docz. Create `gatsby-config.js` in the root of project.
+
+```js
+// gatsby-config.js
+module.exports = {
+  plugins: [
+    {
+      resolve: `gatsby-plugin-sass`,
+      options: {
+        // Override the file regex for SASS
+        sassRuleTest: /\.s(a|c)ss$/,
+        // Override the file regex for CSS modules
+        sassRuleModulesTest: /\.module\.s(a|c)ss$/,
+      },
+    },
+  ],
+};
+```
+
+5. Import `scss` files straight into Component.
+
+   ```jsx
+   import React from 'react';
+   import classes from './Component.module.scss'; // note the changed extension
+
+   const Component = () => <div className={classes.wrapper}>Component</div>;
+   ```
+
+You can see all changes required to enable SASS/SCSS in [corresponding PR](https://github.com/morewings/cra-template-npm-library/pull/11).
+
+### Add PostCSS
+
+1. Install `postcss-cli` and related plugins:
+   ```shell script
+   yarn add --dev postcss-nested postcss-cli postcss-preset-env npm-run-all
+   ```
+2. Modify package scripts:
+
+   ```json
+   {
+     "build:style": "postcss src/**/*.pcss --dir src --base src --ext css",
+     "watch:style": "yarn build:style -w",
+     "start": "npm-run-all -p watch:style start:js",
+     "start:js": "react-scripts start",
+     "build:js": "react-scripts build",
+     "build": "npm-run-all build:style build:js"
+   }
+   ```
+
+3. Add postcss support to Docz. Create `gatsby-config.js` in the root of project.
+
+   ```js
+   // gatsby-config.js
+   module.exports = {
+     plugins: [`gatsby-plugin-postcss`],
+   };
+   ```
+
+4. Add `postcss.config.js` file in the root folder. With following configuration:
+
+   ```js
+   const pkg = require('./package.json');
+
+   module.exports = {
+     plugins: [
+       require('postcss-nested'), // handle nested selectors, like LESS or SASS
+       require('postcss-preset-env')({
+         browsers: pkg.browserslist.production, // use browsers list from production mode
+         stage: 1,
+       }),
+     ],
+   };
+   ```
+
+5. Add rule to `.gitignore` and `.stylelintrc` to ignore all css files, since we are generating them.
+
+   #### .gitignore
+
+   ```gitignore
+   # css
+   *.css
+   ```
+
+   #### .stylelintrc
+
+   ```json
+   {
+     "ignoreFiles": ["**/*.snap", "**/*.css"]
+   }
+   ```
+
+6. Change `.lintstagedrc` to lint `pcss` files instead of `css`.
+
+   ```json
+   {
+     "*.js": ["eslint --fix"],
+     "*.pcss": ["stylelint --fix"]
+   }
+   ```
+
+You can see all changes required to enable PostCSS in [corresponding PR](https://github.com/morewings/cra-template-npm-library/pull/12).
+
+### Add Less
+
+1. Install `less` and related plugins:
+   ```shell script
+   yarn add --dev less less-watch-compiler gatsby-plugin-less npm-run-all
+   ```
+2. Modify package scripts:
+
+   ```json
+   {
+     "build:style": "yarn watch:style --run-once",
+     "watch:style": "less-watch-compiler src src",
+     "start": "npm-run-all -p watch:style start:js",
+     "start:js": "react-scripts start",
+     "build:js": "react-scripts build",
+     "build": "npm-run-all build:style build:js"
+   }
+   ```
+
+3. Add less support to Docz. Create `gatsby-config.js` in the root of project.
+
+   ```js
+   // gatsby-config.js
+   module.exports = {
+     plugins: [`gatsby-plugin-less`],
+   };
+   ```
+
+4. Add rule to `.gitignore` and `.stylelintrc` to ignore all css files, since we are generating them.
+
+   #### .gitignore
+
+   ```gitignore
+   # css
+   *.css
+   ```
+
+   #### .stylelintrc
+
+   ```json
+   {
+     "ignoreFiles": ["**/*.snap", "**/*.css"]
+   }
+   ```
+
+5. Change `.lintstagedrc` to lint `less` files instead of `css`.
+
+   ```json
+   {
+     "*.js": ["eslint --fix"],
+     "*.less": ["stylelint --fix"]
+   }
+   ```
+
+You can see all changes required to enable Less in [corresponding PR](https://github.com/morewings/cra-template-npm-library/pull/10).
+
 ## Peer Dependencies
 
 Please see below. These must be dependencies in your project to use this library

package/build/index.d.ts

@@ -1,5 +1,4 @@
 import theme, { ITheme } from './theme';
 import KibbleThemeProvider from './providers/ThemeProvider';
 import Button from './components/Button';
-import Banner from './components/Banner';
-export { theme, ITheme, KibbleThemeProvider, Button, Banner };
+export { theme, ITheme, KibbleThemeProvider, Button };