Component Documentation and Playgrounds here

Installation

TailwindApp Web UI is available as an npm package.

# install the package into a React application
npm install @tailwindapp/web-ui

| Build Status | Docs Status | |--------------|---------------| | | |

Usage

Here is a quick example to get you started:

import React, {Fragment} from 'react';
import { render } from "react-dom";
import { MessagePopover } from "@tailwindapp/web-ui";

const App = () => (
 <Fragment>
	 <div id="myTarget">My Target</div>
	 <MessagePopover target={'myTarget'} message={'My Message'} show={true} />
 </Fragment>);

render(<App />, document.getElementById("root"));

Contributing to TailwindApp Web UI

Installing to Local System

Clone the repo to your local system and install the packages.

git clone [email protected]:tailwind/web-ui.git
# change into that directory
cd web-ui
# install packages
npm i

Component Architecture

Our convention is to create a directory that matches the component name but in snake-case. So a component named MyTestComponent would be placed inside a directory called my-test-component. Also, there are 4 required files for each component:

• Component main file (my-test-component.tsx)
  • Preferably a functional component (using react hooks if local state is needed)
• Component test file (my-test-component.test.tsx)
• Component Storybook stories file (my-test-component.stories.tsx)
• Component styles file (my-test-component.styles.scss)

NOTE You can use code generation to create this directory and all files (as well as adding the export declaration to the src/lib/index.js file).

Start and Watch Docs (Storybook - docs)

During development, you'll want to hot-reload the documentation pages. By default, this page will start at http://localhost:9009/

# generate documentation and reload when files change
npm run docs:watch

Run and Watch the Playground File

We run a standalone CRA (create-react-app) application. You can use the ./src/index.js file as a "playground" environment. By default, this page will start at http://localhost:3000/tailwind/web-ui.

NOTE The playground file is intentionally ignored in the .gitignore file so you can edit it as needed for your development purposes.

# start and watch the playground environment
npm run start

Developing components alongside the consuming React application with npm link

Sometimes it is helpful to develop new components in isolation but still review them in context of the final consuming application. You can use npm link (docs) to create a symlink to the local @tailwindapp/web-ui from the consuming application. (Consuming application would be an application like tailwind/app).

# from the root of your local install of @tailwindapp/web-ui
npm link
npm run start

# from the root of the consuming application
npm link @tailwindapp/web-ui
npm run start # or whatever command used to 'watch' that application

After linking the local library, you can import a component into the consuming application, make changes to that component and see the changes within your consuming application.

Exposing Components

Before a component can be imported into another application, it must be exposed to the library. This is done by importing the component and then exporting it as a named component within the ./src/index.js file. For example:

export { MessagePopover } from "./message-popover/message-popover";
export { GridTile } from "./grid-tile/grid-tile-view";
export { Button } from "./button/button";
export { SimpleDropdown } from "./simple-dropdown/simple-dropdown"

Then the external application would import a specific component as a named component:

import { MessagePopover } from '@tailwindapp/web-ui';

Code Generation Script

To aid in creating a new component with all required files and export declaration, you can use the code generation script

npm run codegen

Deploying a New Version of the Library

To deploy a new version of the library, you'll need to tag it and push the tag to Github.

To correctly tag the version use the npm version command. This will bump the version of the package and commit it, along with tagging the git commit.

You should follow semver guidelines for version numbers.

See https://semver.org/ for information on versions and see https://docs.npmjs.com/cli/version for more details on how to use npm version

Steps to Tag and Deploy

First, we need to make sure there are no errors by running the two commands.

npm run docs:build

npm run build

Now that we are sure there are no errors, checkout a new branch to make the deployment.

git checkout -b deploy/feature-name

In the new branch, update the version and tag the commit.

npm version patch

Then push the commit and the tag to Github.

git push && git push origin --tags

Create a new pull request.

After merging, AWS will run buildspec.deploy.yml and publish the latest version to NPM.