@watsi/ui

Shared UI components that are used across Watsi Crowdfunding products: watsi.org and our blog.

Currently this module only contains the following components:

• [x] Button (filled, outline, loadable, twitter/facebook)
• [x] Link
• [x] WatsiLogo
• [x] Footer
• [ ] FormField
• [ ] Modal
• [ ] PatientCard

Historical Context

Most of this README was written in 2017 when this repo was created. It was originally created for not just watsi.org and blog.watsi.org, but also UHP aka Meso, which is no longer part of Watsi as of 2020 or so.

I'm writing this in 2024 and have just updated the code to get it working again, and both I and the developer who updated this in 2022 agree that it doesn't make sense to invest in maintaining this separate ui repo.

If you're reading this in, say, 2028 as the only developer at Watsi and this repo and the ghost blog repo haven't been maintained since 2024, you should strongly consider re-imagining the whole setup instead of diving into dependency hell.

One option would be moving these UI components to the main repo, and changing the blog to have a basic Ghost theme instead of a custom theme. If you choose to continue, you might end up spending 10-15 hours instead of the 2 you expected to set up your development environment and update things.

Good luck, future reader!

Getting started

You'll want to run Node 18, and/or use the version manager mise per the README in the main repo.

To start making changes:

npm run dev

This will watch files in src/ for changes and spit out compiled versions in the dist/ folder.

To see changes you make in other repos (eg. watsi/platform, watsi/ghastly), you'll want to npm link your local copy of watsi/ui. Linking tells npm to use a symlinked local copy of a module. This makes changes appear instantaneously, rather than having to npm publish every change. Don't bump the version number until you've completed all testing, or you'll need to npm publish.

To link your local repo:

cd /path/to/this/repo
npm link
cd /path/to/platform
npm link @watsi/ui

Done! Now, when you make changes, those will immediately be reflected in the node_modules folder of the repo you linked it to.

Once you're done making changes, you can

cd /path/to/platform
npm unlink @watsi/ui

To restore the npm copy of @watsi/ui.

Right now the only way to see your changes is by looking at the other repos, so it's important that you test across both watsi/platform and watsi/ghastly before bumping the versions in package.json.

Publishing

This module follows semver, a versioning technique that identifies when breaking changes are made.

• Semver
• Developing (npm run dev)
• Build process (npm run build)
• Publishing to npm (npm version <patch|minor|major> && npm publish)

You'll need to log in to npm publish, and the credentials are in the 1Password Engineering vault.

Using the code

Since we're packaging styles as well as scripts, using this module is a little more involved than a simple npm install @watsi/ui.

For npm-capable environments, we can install the module and require it like so:

import ui from '@watsi/ui';

var { Button, Footer } = ui.components;

function MyComponent() {
  return (
    <div>
      <Button large>Hello world!</Button>
    </div>
  );
}

To import the styles, you can import two CSS files from node_modules. How to import CSS files from node_modules varies by setup, but sass-loader for example uses a ~ prefix:

@import '~@watsi/ui/dist/watsi-variables';
@import '~@watsi/ui/dist/watsi-ui';

For a Sprockets environment, we add node_modules to our asset paths and require the files like any vendor code.

For scripts:

//= require @watsi/ui/dist/watsi-ui

And for styles:

@import '@watsi/ui/dist/watsi-variables';
@import '@watsi/ui/dist/watsi-ui';

Phew. A bit of work, but luckily it only needs to be done once.

About the files

This package spits out several different formats for our code to accommodate the different environments we work in (Sprockets, webpack, etc):

1. An inline <script> compatible format (sourced from index.iife.js, IIFE's)
2. An npm module format (sourced from index.esm.js)
3. An SCSS stylesheet with our colors and mixins (watsi-variables.scss)
4. A compiled CSS stylesheet with utility classes and component code (watsi-ui.css)

On watsi.org, require the IIFE scripts with Sprockets in our components.v3.js, and we require watsi-ui.css and watsi-variables.scss in our v3.scss.

On blog.watsi.org, we use webpack to import ui from '@watsi/ui', which bundles the index.esm.js module into our code. We also import the two CSS files.

Future Plans 2017 and/or Known Issues 2024

1. Components and SCSS variables are the only thing in here right now, but in the future there are lots of potential things for this module to export, such as:

• Icons (note that the lack of icons means the social icons in the footer won't appear unless they're included by the environment, which the blog currently does not)
• Base styles (normalize, globals, etc)

2. There's currently no automated testing.

3. There could be a storybook instance set up in this repo to make developing easier.