-
Notifications
You must be signed in to change notification settings - Fork 377
chore(readme): update react-core readme to new format #4086
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,60 @@ | ||
| # PatternFly React | ||
| This README covers advanced usage topics for PatternFly React users. | ||
|
|
||
| ### Table of contents | ||
| 1. [Applying Overpass Font](#Applying-Overpass-font) | ||
| 2. [Tree shaking](#Tree-shaking) | ||
|
|
||
| ## Applying Overpass font | ||
| If you would like to use Overpass instead of the Red Hat font, simply add the class `.pf-m-overpass-font` to an element that wraps your application (ideally `<html>` or `<body>`) to adopt the CSS changes that would allow opting in to the Overpass font. | ||
|
|
||
|
|
||
| ## Tree shaking | ||
|
|
||
| Ensure optimization.sideEffects is set to true within your Webpack config: | ||
| ```JS | ||
| optimization: { | ||
| sideEffects: true | ||
| } | ||
| ``` | ||
|
|
||
| Use ESM module imports to enable tree shaking with no additional setup required. | ||
| ```JS | ||
| import { TimesIcon } from '@patternfly/react-icons'; | ||
| ``` | ||
|
|
||
| To enable tree shaking with named imports for CJS modules, utilize [babel-plugin-transform-imports](https://www.npmjs.com/package/babel-plugin-transform-imports) and update a babel.config.js file to utilize the plugin: | ||
| ```JS | ||
| require.extensions['.css'] = () => undefined; | ||
| const components = require('@patternfly/react-core/dist/js/components'); | ||
| const beta = require('@patternfly/react-core/dist/js/beta'); | ||
| const layouts = require('@patternfly/react-core/dist/js/layouts'); | ||
|
|
||
| module.exports = { | ||
| presets: ["@babel/preset-react"], | ||
| plugins: [ | ||
| [ | ||
| "transform-imports", | ||
| { | ||
| "@patternfly/react-core": { | ||
| transform: (importName, matches) => { | ||
| let res = '@patternfly/react-core/dist/js/'; | ||
| if (components[importName]) { | ||
| res += 'components'; | ||
| } else if (beta[importName]) { | ||
| res += 'beta'; | ||
| } else if (layouts[importName]) { | ||
| res += 'layouts'; | ||
| } | ||
|
|
||
| res += `/${importName}/${importName}.js`; | ||
| return res; | ||
| }, | ||
| preventFullImport: true, | ||
| skipDefaultConversion: true | ||
| } | ||
| } | ||
| ] | ||
| ] | ||
| } | ||
| ``` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,163 +1,59 @@ | ||
| # @patternfly/react-core | ||
| # PatternFly React - Core | ||
|
|
||
| This package provides Core PatternFly components for the [PatternFly 4][patternfly-4]. | ||
| [](https://lernajs.io/) | ||
| [](https://www.npmjs.com/package/@patternfly/react-core) | ||
| [](https://codecov.io/gh/patternfly/patternfly-react) | ||
|
|
||
| ### Prerequisite | ||
| This project provides the React core components for the [PatternFly project](https://patternfly.org). | ||
|
|
||
| #### Node Environment | ||
| **Community:** [PatternFly website](https://www.patternfly.org) | [Slack](https://slack.patternfly.org) | [Medium](https://medium.com/patternfly) | [Mailing list](https://www.redhat.com/mailman/listinfo/patternfly) | ||
|
|
||
| This project currently supports Node [Active LTS](https://github.com/nodejs/Release#release-schedule) releases. Please stay current with Node Active LTS when developing patternfly-react. | ||
| ### Table of contents | ||
| 1. [Setup](#Setup) | ||
| 2. [Contribution guidelines](#Contribution-guidelines) | ||
| 3. [License](#License) | ||
|
|
||
| For example, to develop with Node 10, use the following: | ||
| ### Setup | ||
|
|
||
| ``` | ||
| nvm install 10 | ||
| nvm use 10 | ||
| ``` | ||
|
|
||
| This project also requires a Yarn version of >=1.6.0. The latest version can be installed [here](https://yarnpkg.com/). | ||
|
|
||
| ### Installing | ||
|
|
||
| ``` | ||
| yarn add @patternfly/react-core | ||
| ``` | ||
|
|
||
| or | ||
|
|
||
| ``` | ||
| npm install @patternfly/react-core --save | ||
| ``` | ||
| Before you begin, check out this [overview of PatternFly](http://patternfly.org/v4/get-started/about) to get familiar with the basic elements of the design system. These instructions also assume that an existing React project is set up. For more information on how to do this, please see our main [README](https://github.com/patternfly/patternfly-react/tree/master/README.md#setup). | ||
|
|
||
| # Usage | ||
| #### Install the @patternfly/react-core NPM package | ||
| * Using npm, run the following command to install: | ||
| ``` | ||
| npm install @patternfly/react-core --save | ||
| ``` | ||
|
|
||
| #### Pre-requisites | ||
| **OR** | ||
|
|
||
| It's strongly advised to use the PatternFly Base CSS in your whole project, or some components may diverge in appearance: | ||
| * Using yarn, run the following command to install: | ||
| ``` | ||
| yarn add @patternfly/react-core | ||
| ``` | ||
|
|
||
| #### Project configuration | ||
| Each PatternFly component already contains the CSS related to the component. In order to have consistent styles throughout the application, PatternFly Base CSS should be used in the project, or some components may diverge in appearance. This import statement should be placed before your main application component is imported. | ||
|
|
||
| ```javascript | ||
| import '@patternfly/react-core/dist/styles/base.css'; | ||
| ``` | ||
|
|
||
| #### Example Component Usage | ||
| #### Example component usage | ||
|
|
||
| ```javascript | ||
| import { Button } from '@patternfly/react-core'; | ||
|
|
||
| export default <Button variant="primary">Button</Button>; | ||
| ``` | ||
|
|
||
| All css related to each component is provided within it. There is no component level CSS to import. | ||
|
|
||
| # Applying Red Hat Fonts (Optional) | ||
| If you would like to use Red Hat fonts instead of Overpass, simply add the class `.pf-m-redhat-font` to an element that wraps your application (ideally `<html>` or `<body>`) to adopt the CSS changes that introduce the Red Hat fonts into PatternFly. | ||
|
|
||
|
|
||
| # Documentation | ||
|
|
||
| This project uses Gatsby. For an overview of the project structure please refer to the [Gatsby documentation - Building with Components](https://www.gatsbyjs.org/docs/building-with-components/). | ||
|
|
||
| A comprehensive list of components and detailed usage of each can be found on the [PatternFly React Docs][docs] website | ||
| You can also find how each component is meant to be used from a design perspective on the [PatternFly 4 Core][patternfly-4] website. | ||
|
|
||
| Note: All commands below assume you are on the root directory in this repository. | ||
|
|
||
| ### Install | ||
|
|
||
| Run to install all the dependencies. | ||
|
|
||
| ```sh | ||
| yarn install && yarn build | ||
| ``` | ||
|
|
||
| ### Running | ||
|
|
||
| To launch the development server and view the workspace: | ||
| All component documentation is available on [PatternFly.org](https://www.patternfly.org/v4/documentation/react/components/aboutmodal). | ||
|
|
||
| ```sh | ||
| yarn start:pf4 | ||
| ``` | ||
| #### Advanced usage | ||
| 1. [Applying Overpass font](../../ADVANCED-USAGE-README.md#Applying-Overpass-font) | ||
| 2. [Tree shaking](../../ADVANCED-USAGE-README.md#Tree-shaking) | ||
|
|
||
| Go to localhost:8000. | ||
| ### Contribution guidelines | ||
| All React contributors must first be [PatternFly community contributors](https://www.patternfly.org/v4/contribute/about). If you're already a PatternFly community contributor, check out the [React contribution guidelines](https://github.com/patternfly/patternfly-react/tree/master/CONTRIBUTING.md) to make React contributions. | ||
|
|
||
| ### Building | ||
| ### License | ||
| PatternFly React is licensed under the [MIT License](https://github.com/patternfly/patternfly-react/tree/master/LICENSE). | ||
|
|
||
| To build the site: | ||
|
|
||
| ```sh | ||
| yarn build:docs | ||
| ``` | ||
|
|
||
| # Contributing Components | ||
|
|
||
| This library makes use of the babel plugin from [@patternfly/react-styles](../react-styles/README.md) to enable providing the CSS alongside the components. This removes the need for consumers to use (style|css|sass)-loaders. For an example of using CSS from core you can reference [Button.js](./src/components/Button/Button.js). For any CSS not provided by core please use the `StyleSheet.create` utility from [@patternfly/react-styles](../react-styles/README.md). This will prevent collisions with any consumers, and allow the CSS to be bundled with the component. | ||
|
|
||
| ### Building | ||
|
|
||
| ``` | ||
| yarn build | ||
| ``` | ||
|
|
||
| Note the build scripts for this are located in the root package.json under `yarn build`. | ||
|
|
||
| ### Testing | ||
|
|
||
| Testing is done at the root of this repo. To only run the patternfly-react tests: | ||
|
|
||
| ``` | ||
| yarn test packages/patternfly-4/react-core | ||
| ``` | ||
|
|
||
| [patternfly-4]: https://github.com/patternfly/patternfly-next | ||
| [docs]: https://patternfly-react.surge.sh/patternfly-4 | ||
|
|
||
|
|
||
| ## Tree Shaking | ||
|
|
||
| Ensure optimization.sideEffects is set to true within your Webpack config: | ||
| ```JS | ||
| optimization: { | ||
| sideEffects: true | ||
| } | ||
| ``` | ||
|
|
||
| Use ESM module imports to enable tree shaking with no additional setup required. | ||
| ```JS | ||
| import { TimesIcon } from '@patternfly/react-icons'; | ||
| ``` | ||
|
|
||
| To enable tree shaking with named imports for CJS modules, utilize [babel-plugin-transform-imports](https://www.npmjs.com/package/babel-plugin-transform-imports) and update a babel.config.js file to utilize the plugin: | ||
| ```JS | ||
| require.extensions['.css'] = () => undefined; | ||
| const components = require('@patternfly/react-core/dist/js/components'); | ||
| const beta = require('@patternfly/react-core/dist/js/beta'); | ||
| const layouts = require('@patternfly/react-core/dist/js/layouts'); | ||
|
|
||
| module.exports = { | ||
| presets: ["@babel/preset-react"], | ||
| plugins: [ | ||
| [ | ||
| "transform-imports", | ||
| { | ||
| "@patternfly/react-core": { | ||
| transform: (importName, matches) => { | ||
| let res = '@patternfly/react-core/dist/js/'; | ||
| if (components[importName]) { | ||
| res += 'components'; | ||
| } else if (beta[importName]) { | ||
| res += 'beta'; | ||
| } else if (layouts[importName]) { | ||
| res += 'layouts'; | ||
| } | ||
|
|
||
| res += `/${importName}/${importName}.js`; | ||
| return res; | ||
| }, | ||
| preventFullImport: true, | ||
| skipDefaultConversion: true | ||
| } | ||
| } | ||
| ] | ||
| ] | ||
| } | ||
| ``` |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
👍