Elements is a set of carefully crafted, high quality React UI components, designed for the Allthings Platform.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

@allthings/elements

npm version Build Status Renovate enabled

Elements is a set of carefully crafted, high quality React UI components, that Allthings uses to build their mobile app.

Installation

Elements are available on npm package.

yarn add @allthings/elements

Please note that @allthings/elements is still under heavy development.

Usage

Here is a quick example to get you started, it's all you need:

import React from 'react'
import { render } from 'react-dom'
import Button from '@allthings/elements/molecules/Button'

function App() {
  return <Button>Hello World</Button>
}

render(<App />, document.querySelector('#app'))

Notes:

fetch

@allthings/elements uses fetch and expects it to be globally available. For example cross-fetch can be used at the entry point of the app:

import 'cross-fetch/polyfill'

i18n

The CDNIntlProvider fetches translations from the Allthings CDN.

If you want to use the component make sure to also install the peer dependency react-intl.

We don't export the CDNIntlProvider from the index file, so it's necessary to import it directly from its destination:

import CDNIntlProvider from '@allthings/elements/behaviour/CDNIntlProvider'

Examples

Are you looking for some full example projects to get started? Check this out.

Documentation

Check out our documentation website.

Writing unit tests

Whenever you create or edit a React component or any other JavaScript file, you must update or create a corresponding test file in the same directory.

By convention the test file should be named after the file's name with an additional .test. part:

SomeDir
  | - MyButton.jsx
  | - MyButton.test.jsx
SomeOtherDir
  | - utils.js
  | - utils.test.js

To manually trigger the unit tests, run:

yarn test

You can also use the corresponding watch task:

yarn watch:test

The unit tests are performed using the Jest platform, please refer to its documentation.

React component testing is based on the Enzyme testing utility, please refer to its documentation.

The use of snapshots generated by the toMatchSnapshot() method is strongly encouraged. Those snapshots must be always commited as they are a very useful tool whenever you want to make sure your UI does not change unexpectedly

Local development in another app

If you want to make changes to @allthings/elements and see them taking effect in your app instantly, we've got good news for you. Just follow these instructions…

🛠 Initial steps

  1. Install yalc: yarn global add yalc
  2. Create a build with yarn build.
  3. Publish the build folder yalc publish build. Don't worry this will only 'publish' to a local store located on the hard disk (see yalc docs to read more about this).

tl;dr

yarn global add yalc
cd @allthings/elements
yarn build
yalc publish build

☕️ Start developing in your app

  1. Go to the app, which will consume the local elements repository and execute yalc add --link @allthings/elements
  2. Run yarn so it will fetch the local repository now.
  3. Go back to @allthings/elements repository.
  4. Run yarn babel:watch.
  5. Make some changes 🧚‍✨
  6. Run yalc push build.
  7. Changes will be propagated to all linked projects.
  8. Everytime you do some changes you can run yalc push build again.

tl;dr

cd /path/to/project
yalc add --link @allthings/elements
yarn

cd /path/to/@allthings/elements
yarn babel:watch
# Do some some changes
yalc push build

What does yalc add --link do?

  • Create a folder .yalc with the contents of the current local @allthings/elements repository.
  • Create a yalc.lock file for computational stuff.
  • Modify the package.json to load the package from link:.yalc/@allthings/elements.

Be sure to not commit any of these changes. Consider adding the created files to .gitignore. See yalc for more information.

🏁 Clean up, after you're done

cd /path/to/project
yalc remove @allthings/elements
yarn

⚠️ Note:

webpack externals:

If you're using server side rendering alongside with webpack-node-externals, be sure to add everything elements related to the whitelist:

// webpack.config.js
{
  externals: externals({ whitelist: [/^@allthings\/elements/] }),
  // ...
}
Serverless with serverless-webpack

It seems that serverless-webpack does not recognize the link: format in, as it doesn't support yarn yet.

Rather than using yalc add --link @allthings/elements you should use yalc add @allthings/elements.