shamash2014 / zacs Goto Github PK

ZACS turns React components that look like this:

import zacs from '@nozbe/zacs'
import style from './style'

const Box = zacs.view(style.box, { isHighlighted: style.highlighted })

const rendered = <Box isHighlighted />

Into optimized code that looks like this (web):

const rendered = <div className={style.box + ' ' + style.highlighted} />

Or this (React Native):

import { View } from 'react-native'

const rendered = <View style={[style.box, style.highlighted]} />

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 <div className> and <View style> manually. That's because the library doesn't actually exist at runtime, it's entirely implemented as a Babel 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.

npm install @nozbe/zacs

or

yarn add @nozbe/zacs

Then add ZACS to your Babel config (.babelrc or babel.config.js):

{
  "plugins": [
+   ["@nozbe/zacs/babel", {
+     "platform": "web", // or "native"
+     "production": true // pass `false` to enable debug attributes
+   }]
  ]
}

For web support, you need a temporary workaround in your Webpack config, because zacs releases are not compiled yet. Sorry - this is a temporary inconvenience:

  module: {
    rules: [
      ...
      {
        test: /\.js$/,
        exclude: {
          and: [/(node_modules)/, { not: [/zacs/] }],
        },
        use: {
          loader: 'babel-loader',
          // ...
        },
      },
    },
    ...
  }

import zacs from '@nozbe/zacs'

const Box = zacs.view() // or zacs.view(null)
const Label = zacs.text()

const rendered = <Box><Label>Hello</Label></Box>

const rendered = <div><span>Hello</span></div>

import { View, Text } from 'react-native'

const rendered = <View><Text>Hello</Text></View>

import styles from './styles'

const Box = zacs.view(styles.box) // or zacs.text

const rendered = <Box />

const rendered = <div className={styles.box} />

import { View } from 'react-native'

const rendered = <View style={styles.box} />

const Box = zacs.view(styles.box, {
  isHighlighted: styles.isHighlighted,
  isVisible: styles.isVisible,
})

const rendered = <Box isHighlighted={reactions > 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.

const rendered = <div className={styles.box
                                + ' ' + styles.isVisible
                                + (reactions > 0) ? (' ' + styles.isHighlighted) : ''} />

import { View } from 'react-native'

const rendered = <View style={[styles.box,
                              styles.isVisible,
                              reactions > 0 && styles.isHighlighted]} />

const Box = zacs.view(styles.box, null, {
  width: 'width',
  color: 'backgroundColor',
})

const rendered = <Box width={100} color="#80EADC" />

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.

const rendered = <div className={styles.box} style={{ width: 100, backgroundColor: '#80EADC' }} />

import { View } from 'react-native'

const rendered = <View style={[styles.box, { width: 100, backgroundColor: '#80EADC' }]} />

import Touchable from 'components/Touchable'

const Button = zacs.styled(Touchable, styles.button, null, {
  width: 'width'
})

const rendered = <Button width={500} />

import Touchable from 'components/Touchable'

const rendered = <Touchable className={styles.button} style={{ width: 500 }} />

import Touchable from 'components/Touchable'

const rendered = <Touchable style={[styles.button, { width: 500 }]} />

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.

const Root = zacs.view(styles.root)

export default const Touchable = props => {
  return <Root zacs:inherit={props} />
}

TODO: I don't love the zacs:inherit name — if you have a better suggestion, let us know!

export default const Touchable = props => {
  return <div className={styles.root + ' ' + (props.className || '')} style={props.style} />
}

import { View } from 'react-native'

export default const Touchable = props => {
  return <View style={[styles.root].concat(props.style || [])} />
}

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.

const Paragraph = zacs.styled({ web: 'p', native: zacs.text }, styles.paragraph)

const rendered = <Paragraph>Hello world!</Paragraph>

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)

TODO: Passing zacs.text/view as parameter seems magic and gross. If you have a better idea for this API, let us know!

const rendered = <p className={styles.paragraph}>Hello world!</p>

import { Text } from 'react-native'

const rendered = <Text style={styles.paragraph}>Hello world!</Text>

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:

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).

export const Box = (props) => {
  return <div className={styles.box}>{props.children}</div>
}

export const Label = (props) => {
  return (
    // Note that `numberOfLines` is not passed on because it's not a DOM attribute
    <span className={styles.label + (props.isBold ? ' ' + styles.labelBold : '')} title={props.title}>
      {props.children}
    </span>
  )
}

// We add forwardRef if `ref` is an allowed attribute
export const Wrapper = React.forwardRef((props, ref) => {
  return <div className={styles.wrapper} ref={ref}>{props.children}</div>
})

import { View, Text } from 'react-native'

export const Box = (props) => {
  return <Text style={styles.box}>{props.children}</Text>
}

export const Label = (props) => {
  return (
    <Text style={[styles.label, props.isBold && styles.labelBold]}
          title={props.title}
          numberOfLines={props.numberOfLines}>
      {props.children}
    </Text>
  )
}

export const Wrapper = React.forwardRef((props, ref) => {
  return <Text style={styles.wrapper} ref={ref}>{props.children}</Text>
})

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

// style.native.js
import { StyleSheet } from 'react-native'

export default StyleSheet.create({
  box: {
    backgroundColor: "#80EADC",
    width: 500,
  },
  highlighted: {
    // ...
  },
})

See React Native documentation for more details.

Web

We recommend using PostCSS in your Webpack config to make CSS styles importable from JS.

/* 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!

WIP - Please contribute!

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 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!

ZACS was created by @Nozbe. Main author and maintainer is Radek Pietruszewski.

ZACS is available under the MIT license. See the LICENSE file for more info.