https://github.com/traefik/faency
Faency is the Traefik Labs React component library
https://github.com/traefik/faency
react react-component react-library
Last synced: 23 days ago
JSON representation
Faency is the Traefik Labs React component library
- Host: GitHub
- URL: https://github.com/traefik/faency
- Owner: traefik
- License: apache-2.0
- Created: 2019-12-02T16:34:44.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2025-01-21T15:19:45.000Z (about 1 year ago)
- Last Synced: 2025-03-28T20:51:45.017Z (10 months ago)
- Topics: react, react-component, react-library
- Language: TypeScript
- Homepage: https://traefik.github.io/faency
- Size: 5.71 MB
- Stars: 40
- Watchers: 5
- Forks: 14
- Open Issues: 31
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Traefik Labs Faency
This is the React component library and design system for [Traefik Labs](https://traefik.io).
Built with React, Typescript, [Stitches](https://github.com/modulz/stitches) and [Radix UI Primitives](https://radix-ui.com/primitives/docs/overview/introduction).
## Demo (Storybook)
You can find the Storybook with an example for every component in this library [here](https://traefik.github.io/faency).
## Getting started
### How to use Faency
```sh
npm install @traefik-labs/faency@next
# or
yarn add @traefik-labs/faency@next
```
#### Using Stitches Components (Current)
Wire up the FaencyProvider which will hold the context with the Theme configuration:
> The provider accepts one parameter besides the `children`, which is the `primaryColor`, that will be used to build the colors used on the Theme. This color can be one of the colors exported by the `Stitches` config, just by adding `$` as a prefix, or can be any string that represents a CSS color.
```jsx
import { FaencyProvider } from '@traefik-labs/faency';
const App = () => {/* your app */};
```
Then you are ready to import components and use them on your project:
```jsx
import { Flex, styled } from '@traefik-labs/faency';
const Container = styled(Flex, {
padding: '$3',
bg: '$black', // alias for backgroundColor
mx: '$2', // alias for margin left and right
});
const MyComponent = () => {children};
```
#### Using Vanilla Extract Components (New - Recommended)
For better performance with static CSS, use the new Vanilla Extract components:
1. Import the CSS file in your app's entry point:
```jsx
import '@traefik-labs/faency/dist/style.css';
```
2. Wrap your app with the VanillaExtractThemeProvider:
```jsx
import { VanillaExtractThemeProvider } from '@traefik-labs/faency';
import { BoxVanilla, BadgeVanilla } from '@traefik-labs/faency';
const App = () => (
Hello Faency!
);
```
> **Note**: Vanilla Extract components use static CSS generated at build time, providing better performance than runtime CSS-in-JS. Components with the `Vanilla` suffix (e.g., `BadgeVanilla`, `BoxVanilla`) require the CSS import above.
## How to contribute
- Make sure you have Node 18+, or if you prefer, you can work in a Docker container:
```sh
docker run -it -v $(pwd):/usr/local/src/ -w /usr/local/src/ -p 3000:3000 node:latest bash
```
- Install the project dependencies
```sh
yarn install
```
- Patch the package
Stitches package needs to be patched after the upgrade to TypeScript version 5. You can run this script after installing the dependencies to apply the patch:
```sh
yarn patch-package
```
- Run the Storybook
```sh
yarn storybook
```
At this point, Storybook should automatically open up in your browser and you can start coding, it has hot reload so it will automatically re-render whenever a change is detected on the code.
### Writing stories
We use Stories to demonstrate how components can behave and which variants they can take, so it's expected that every component has a Story.
Check out how to create stories in the [Storybook Docs](https://storybook.js.org/docs/react/writing-stories/introduction).
### Opening Pull requests
[Pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) are always welcome, but if you have a big change that you would like to work on, it's recommended to open an issue, so we can discuss it beforehand.
A good PR is small, focuses on a single feature or improvement, and clearly communicates the problem it solves.
Try not to include more than one issue in a single PR. It's much easier for us to review multiple small pull requests than one that is large and unwieldy.
Note we follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/).
Please follow the provided [PR template](/.github/pull_request_template.md).
### Release process
We use [semantic-release/semantic-release](https://github.com/semantic-release/semantic-release) to automagically release any commit on the `master` branch.
Recommended conventional commit types:
```json
["build", "chore", "ci", "docs", "feat", "fix", "revert", "test"]
```
- `build`/`chore`: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
- `ci`: Changes to CI configuration files and scripts (examples: CircleCi, SauceLabs)
- `docs`: Documentation (comments) only changes
- `feat`: A new feature
- `fix`: A bug fix
- `revert`: Reverts a previous commit
- `test`: Adding missing tests or correcting existing tests
Breaking change syntax:
```text
!:
```
Matching between commit type and release
```js
[
{ breaking: true, release: 'major' },
// types impacting release version
{ revert: true, release: 'patch' },
{ type: 'feat', release: 'minor' },
{ type: 'fix', release: 'patch' },
{ type: 'perf', release: 'patch' },
];
```
See [semantic-release/commit-analyzer](https://github.com/semantic-release/commit-analyzer#readme) for more information.