blockparty-native-storybook v1.0.2

BlockParty-Native 📱

BlockParty-Native is a React Native component library for the Endpoint Design System.

• Storybook in Expo - View with Expo Go app - iOS or Android
• Storybook in web - Hosted on Netlify. Password can be found in 1Password
• Documentation - Research, Guidelines, UX and Brand

Tech Stack

• Expo - Platform for building React Native apps
• Restyle - A type-enforced system for building UI components in React Native with TypeScript.
• react-native-build-bob - A simple CLI to scaffold and build React Native libraries

Table of Contents

• BlockParty-Native
  • Table of Contents
  • Getting Started
    • Usage
    • Scripts
  • Contributing
  • Gotchas

Getting Started

Installing BlockParty

yarn add @endpoint/blockparty-native

Usage

Wrap your native app with the BlockPartyProvider component at the root level:

import { BlockPartyProvider } from '@endpoint/blockparty-native';

const App = props => (
  <BlockPartyProvider>
    {props.children}
  </BlockPartyProvider>
);

Features

Accessing the Theme

If you need to manually access the theme outside of a component created with BlockParty-Native, use the useTheme hook:

const Component = () => {
  const theme = useTheme<Theme>();
  const {cardPrimaryBackground} = theme.colors;
  // ...
};

By doing this instead of directly importing the theme object, it becomes easy to swap the theme out during runtime to for example implement a dark mode switch in your app.

Contributing

Local Development

To run BlockParty locally:

1. Clone repo: git clone https://github.com/endpointclosing/blockparty-native
2. Install dependencies: cd blockparty-native && yarn
3. Run Storybook: yarn start

Scripts

yarn ios or yarn android

Runs Storybook-Native in iOS/Android simulator.

yarn storybook:web

Uses Expo Web to run Storybook-Native in the browser. Open http://localhost:19006 to view it in the browser.

Note: Expo Web is still an experimental feature Runs Storybook server in the web for easier navigation.

yarn build-storybook:web

Builds Storybook-Native for the web and outputs to web-build folder, which is used by a Netlify webhook to:

1. Generate a PR preview
2. Handle deploying build to Netlify web server

Latest Storybook-Native builds can be viewed on Netlify

yarn build

Bundles BlockParty-Native library using react-native-builder-bob for CommonJS and ESM formats with TypeScript support. Build will output to dist directory.

yarn test

Runs jest tests with coverage report

yarn plop {NewComponent}

Plop is used to generate boilerplate files for your component with tests and examples. Your component will automatically be added to the /src/components directory like so:

src
└── components
    └── {NewComponent}
        ├── index.tsx
        ├── index.test.tsx
        └── examples.tsx

Upgrading Dependencies

BlockParty-Native uses Expo as a platform for developing native components. When upgrading dependencies, we'll need to use the Expo CLI since it manual upgrades can cause syncing issues. To upgrade dependencies, run the following command and follow instructions:

expo upgrade

Branching

• Create from master
• Branch names:
  • issue/[JIRA-TICKET-ID]
  • bug/[JIRA-TICKET-ID]
  • poc/[brief description]

Commits & Changelog

• Maintain a clear and readable commit history so that it is easy to follow the steps you took.
• Squash commits if your history becomes more readable with fewer more distinct commits. Exercise good judgment.
• Make use of the yarn co command to properly format commit messages, making it possible to have automated release notes and more. Your new git flow should be as follows:
  • git add <files>
  • yarn commit (scaffolds commit criteria)
  • git push -u origin <branch-name>

Code style

• When developing components, be sure to enable Prettier to automatically format your code

Gotchas

Github workflow

Please do not use your Personal Access Tokens to store as Github secrets/environment variables. For read/write permissions, please use the organization-adopted secret - ENDPOINT_ENG_GITHUB_TOKEN

react-native-builder-bob

There's currently an issue where the default build behavior outputs all files, include tests and sourcemaps. There doesn't seem to be a configurations object to exclude the files so we'll have to follow up with an issue report to the library maintainers.

Storybook web build

If you run build-storybook:web locally, it will output the Storybook-web build in /web-build. Unfortunately, this will need to be committed to the repo for deploying to Netlify, otherwise the pipeline will fail.

Publishing Storybook-Native to Expo servers

Using expo publish will deploy the native builds to npm as well as Expo's servers. Since our repo contains options for building both components and Storybook, we have prioritized treating the build for components as a first-class citizen. Therefore, the requirements to upload Storybook in Expo is as follows:

1. Update package.json to:

{
  "name": "blockparty-native-storybook",
  "version": "1.0.1"
}

Note: Since we don't have a paid Expo account, these builds are automatically scoped to the user's npm account, in this case Binh Nguyen. Please reach out to Binh to get the latest npm version for this particular build.

2. In app.json, change all references of "BlockParty-Native" to "BlockParty-Native-StoryBook"
3. Run yarn publish
4. Once successful, remove changes made in package.json and app.json. Do NOT commit these as saved changes as this will affect the component library build in Endpoint's npm account.
5. Changes should be published to Binh's Expo account available here. If you are unable to view the link, please reach out to Binh for member invite.