Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Nozbe/zacs
Zero Abstraction Cost Styling ⚡️👨🎨 (for React DOM & React Native)
https://github.com/Nozbe/zacs
hacktoberfest react react-native
Last synced: 14 days ago
JSON representation
Zero Abstraction Cost Styling ⚡️👨🎨 (for React DOM & React Native)
- Host: GitHub
- URL: https://github.com/Nozbe/zacs
- Owner: Nozbe
- License: mit
- Created: 2019-08-11T14:47:50.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2023-08-28T11:06:09.000Z (about 1 year ago)
- Last Synced: 2024-09-18T17:26:14.761Z (about 2 months ago)
- Topics: hacktoberfest, react, react-native
- Language: JavaScript
- Homepage:
- Size: 17.8 MB
- Stars: 429
- Watchers: 16
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
👨🎨 Component styling with no performance penalty for React and React Native ⚡️
## What is `zacs`?
| 
|
| ---- |
|
📺 A Successful Web & React Native Sharing Strategy
|
**ZACS** turns React components that look like this:
```js
import zacs from '@nozbe/zacs'
import style from './style'
const Box = zacs.view(style.box, { isHighlighted: style.highlighted })
const rendered =
```
Into **optimized** code that looks like this (**web**):
```js
const rendered =
```
Or this (**React Native**):
```js
import { View } from 'react-native'
const rendered =
```
## Pitch
**ZACS** (Zero Abstraction Cost Styling) is a super-fast component styling library for cross-platform React web and React Native apps.
**Super-fast** as in: there is no difference between using ZACS and writing `
` and `` manually. That's because **the library doesn't actually _exist_** at runtime, it's entirely implemented as a [Babel](https://babeljs.io) plugin, which compiles the "styled components" syntax down to bare metal.
And because **ZACS** hides the API difference between web (DOM) and React Native, you can build a web and RN app with shared codebase without [`react-native-web`](https://github.com/necolas/react-native-web).
## Installation
```sh
npm install @nozbe/zacs
```
or
```sh
yarn add @nozbe/zacs
```
Then add ZACS to your Babel config (`.babelrc` or `babel.config.js`):
```diff
{
"plugins": [
+ ["@nozbe/zacs/babel", {
+ "platform": "web", // "web" or "native"
+ "production": false / true, // pass `false` to enable debug attributes
+ "keepDeclarations": false // (optional) pass `true` to keep zacs.xxx variable declarations in output
+ }]
]
}
```
## Using `zacs`
### Unstyled view or text
```js
import zacs from '@nozbe/zacs'
const Box = zacs.view() // or zacs.view(null)
const Label = zacs.text()
const rendered = Hello
```
See compiled output
**Web:**
```js
const rendered =
Hello
```
**React Native:**
```js
import { View, Text } from 'react-native'
const rendered = Hello
```
### Simple styled view or text
```js
import styles from './styles'
const Box = zacs.view(styles.box) // or zacs.text
const rendered =
```
See compiled output
**Web:**
```js
const rendered =
```
**React Native:**
```js
import { View } from 'react-native'
const rendered =
```
### Conditional styles
```js
const Box = zacs.view(styles.box, {
isHighlighted: styles.isHighlighted,
isVisible: styles.isVisible,
})
const rendered = 0} isVisible />
```
Declare conditional styles as `{ [propName: string]: RNStyleOrClassName }`. If a specified prop is
passed to the component with a truthy value, the corresponding style will be added.
See compiled output
**Web:**
```js
const rendered =
0) ? (' ' + styles.isHighlighted) : ''} />
```
Please note:
- conditions are inlined whenever possible (when a constant is passed to a styling prop)
- styling props are removed from the compiled output
**React Native:**
```js
import { View } from 'react-native'
const rendered = 0 && styles.isHighlighted]} />
```
### Adding style attributes (via individual props)
```js
const Box = zacs.view(styles.box, null, {
width: 'width',
color: 'backgroundColor',
})
const rendered =
```
Declare CSS / React Native `StyleSheet` attributes available as component properties with `{ [propName: string]: CSSOrRNStyleAttributeName }`.
**Gotcha:** If you pass a style attribute at all, *it will override* the main and conditional styles, even if the value is `undefined`.
See compiled output
**Web:**
```js
const rendered =
```
**React Native:**
```js
import { View } from 'react-native'
const rendered =
```
### Adding styles directly
```js
const Box = zacs.view(styles.box)
const rendered =
```
This is equivalent to the example above, but instead of predefining list of props that turn into styles,
we pass styles directly. Note that this only works on ZACS components.
### Multiple unconditional styles
```js
import styles from './styles'
const TitleText = zacs.text([styles.text, styles.titleText])
const rendered =
```
See compiled output
**Web:**
```js
const rendered =
```
**React Native:**
```js
import { Text } from 'react-native'
const rendered =
```
### Styling custom components
```js
import Touchable from 'components/Touchable'
const Button = zacs.styled(Touchable, styles.button, null, {
width: 'width'
})
const rendered =
```
See compiled output
**Web:**
```js
import Touchable from 'components/Touchable'
const rendered =
```
**React Native:**
```js
import Touchable from 'components/Touchable'
const rendered =
```
### Making stylable components
To define new components that you can style using `zacs.styled`, use the special `zacs:inherit` prop
to let **ZACS** know you want styles from `props.style` / `props.className` added in.
```js
const Root = zacs.view(styles.root)
export default const Touchable = props => {
return
}
```
See compiled output
**Web:**
```js
export default const Touchable = props => {
return
}
```
**React Native:**
```js
import { View } from 'react-native'
export default const Touchable = props => {
return
}
```
### Configuring output component/element types
Sometimes you need to style a different component on `web` and `native`. To do this, use
`zacs.styled` with `{ web: ComponentType, native: ComponentType }` instead of a direct component reference.
```js
const Paragraph = zacs.styled({ web: 'p', native: zacs.text }, styles.paragraph)
const rendered = Hello world!
```
As parameters, you can pass:
- built in element type (string - `p`, `div`, `form`)
- a component reference
- magic `zacs.text` or `zacs.view` (this is so you can easily fall back to RN View/Text without importing `react-native`)
If you're only building for one platform, you can also reference built-ins like this:
```js
const Paragraph = zacs.styled('p', styles.paragraph) // NOTE: No web/native, because this is web-only code
```
**TODO:** Passing `zacs.text/view` as parameter seems magic and gross. If you have a better idea for this API, let us know!
See compiled output
**Web:**
```js
const rendered =
Hello world!
```
**React Native:**
```js
import { Text } from 'react-native'
const rendered = Hello world!
```
### Exporting ZACS components
`zacs.view/text/styled` are special **declarations** for the compiler, not real components — that's the whole point of "zero abstraction cost styling".
Unfortunately, this means that you can only use those components in the same file in which they're defined, and you can't export it. And this is how you should use `zacs` most of the time. But sometimes, to avoid repetitive code, you really need this.
In that case, use `zacs.createView/Text/Styled`, which actually creates a real component:
```js
export const Box = zacs.createView(styles.box)
export const Label = zacs.createText(styles.label, {
isBold: style.labelBold,
}, null, ['title', 'numberOfLines'])
export const Wrapper = zacs.createView(styles.wrapper, null, null, ['ref'])
```
You must declare (in the last argument) all non-zacs props you want to be able to pass into the component you're styling (component props, DOM attributes, `ref`, and `zacs:inherit`, `zacs:style`).
Hey, that's really annoying, why do I need to do this?
A distinction between `view` and `createView` is necessary because Babel is a single file compiler, and
it does not have visibility to imports, so an imported component can't be magically transformed into a `
` or ``.
So we have to de-optimize and do the next best thing -- export an actual component. Not quite `zero abstraction cost`, but almost.
There is another limitation: because the declaration doesn't see the callsite, we don't know whether
someone wants to pass props (DOM attributes or View/Text RN props) to the underlying component,
and we can't use `{...props}`, because you can't pass arbitrary attributes to DOM elements in ReactDOM
(it will throw errors and can have unexpected side effects).
Honestly, needing to declare all used props is super annoying and I hate it. If you have a better idea on how to tackle this while staying as close as possible to the _zero abstraction cost_ ideal, **please let us know!**.
See compiled output
**Web:**
```js
export const Box = (props) => {
return
{props.children}
}
export const Label = (props) => {
return (
// Note that `numberOfLines` is not passed on because it's not a DOM attribute
{props.children}
)
}
// We add forwardRef if `ref` is an allowed attribute
export const Wrapper = React.forwardRef((props, ref) => {
return
{props.children}
})
```
**React Native:**
```js
import { View, Text } from 'react-native'
export const Box = (props) => {
return {props.children}
}
export const Label = (props) => {
return (
{props.children}
)
}
export const Wrapper = React.forwardRef((props, ref) => {
return {props.children}
})
```
### Style precedence
From least important to most important:
- main style (first argument to `zacs.xxx()`)
- conditional styles (second argument to `zacs.xxx()`)
- styles added via props (third argument to `zacs.xxx()`)
- styles added via `zacs:style`
- styles added via `zacs:inherit`
For example, `width` passed via `zacs:inherit` will override `width` added via props.
## Defining styles
Unlike popular "CSS-in-JS" libraries, `zacs` only provides the "component styling" part, but styles
themselves are defined in a separate file. Here is how you define them.
**React Native**
```js
// style.native.js
import { StyleSheet } from 'react-native'
export default StyleSheet.create({
box: {
backgroundColor: "#80EADC",
width: 500,
},
highlighted: {
// ...
},
})
```
See [React Native documentation](https://facebook.github.io/react-native/docs/stylesheet) for more details.
**Web**
We recommend using [PostCSS](https://postcss.org) in your Webpack config to make CSS styles importable from JS.
```css
/* style.web.css */
.box {
background: #80EADC;
width: 500px;
}
.highlighted {
/* ... */
}
```
**ZACS shared styles**
We're thinking of extending ZACS to defining styles, so that you can declare styles once in CSS and have them compile to both CSS and React Native StyleSheet in a "zero abstraction cost" fashion. If you're interested in this project — please contact us!
## Troubleshooting
WIP - Please contribute!
## Contributing
**ZACS is an open-source project and it needs your help to thrive!**
If there's a missing feature, a bug, poor documentation, or other improvement you'd like, don't ask what we can do to help you, **ask what you can do to help the community**. Feel free to open an issue to get some guidance, and then please [send a pull request](https://github.com/Nozbe/zacs/compare) addressing your issue!
If you make a non-trivial contribution, email me, and I'll send you a nice ZACS sticker!
If you make an app using ZACS, please let us know!
## Author and license
**ZACS** was created by [@Nozbe](https://github.com/Nozbe). Main author and maintainer is [Radek Pietruszewski](https://github.com/radex).
**ZACS** is available under the MIT license. See the [LICENSE file](./LICENSE) for more info.