@3t-transform/threeteeui

TTTX Library Vision

• To create versioned components where each micro-frontend may use any version it chooses.
  • Why? - Our root frontend contains many micro-frontends. Each one might have a diffrent version of these components loaded at any time. We must not let a change in one MFE affect another MFE loaded at the same time.
• To keep the components extremely lightweight, use as few dependencies as possible. Keep the individual components in the low KB, not the MB.
  • Why? - When there are multiple versions of the same component loaded, we need to keep them extremely lightweight. Most simple components can be executed in a few dozen KB.
• No CSS frameworks. Use only the minimum styles to get the job done.
  • Why? - This means we can be sure that we only load code we are using.
• No external styles. A component must style itself and be inside a shadow DOM so that styles from the external application cannot leak inside.
  • Why? - We cannot have any components being affected by the styles of the surrounding application. The component must be entirely self-contained.
• No leaking styles. A component must not infect the application with its styles.
  • Why? - The same goes both ways, the component styles must not affect the surrounding application.
• Create only components as we need them. YAGNI applies.
  • Why? - It's about Agile. We need to deliver value to the customer (our developers) as soon as possible for their feedback, and so they can deliver value to their customers (our users). If a certain component is required, it will crop up, and then we will make it.

Getting Started

Pull down this repo and run:

yarn
yarn start

To build the component for production, run:

yarn build

To run the unit tests for the components, run:

yarn test

To see the components in Storybook, run:

yarn start
yarn storybook

Need help? Check out our docs.

Release Process

To release a new version of the library, follow these steps:

1. Update the version number in the package.json file according to semantic versioning.
2. Push the changes to the remote master branch.
3. This will trigger a build and run the tests on the CI/CD pipeline.
4. If the tests pass, a new tag will be created.
5. If the tests fail, the release process will be halted and you will need to fix the issues before trying again.
6. Run the release to npm action manually to release the components to the NPM registry.

Make sure to follow the semantic versioning guidelines when updating the version number. This will help users understand the impact of the changes in the new version and avoid breaking changes.

Usage

You'll find the NPM package here: https://www.npmjs.com/package/@3t-transform/threeteeui

In your MFE, install the version of the library you want, like this:

yarn add @3t-transform/threeteeui@1.0.1 --exact

Note that we used the version after the @ symbol, and we also give the --exact parameter, so that we do not get the ^ or ~ symbols in the package.json. We do not want the version to change or drift unless you explicitly say so.

Now, in your MFE, (assuming it is stencil in this case), import the components

import '@3t-transform/threeteeui/dist/components';

Now you can use your shared components in the MFE:

<tttx-button_1_0_1>I am version 1.0.1!</tttx-button_1_0_1>

• Remember the closing tags too.
• Keep only a single version in your MFE, do not mix and match.
• As technical debt, always try to keep up with the most recent version.

How does that work internally?

All components are suffixed with _localcomponent. You MUST remember this when building more components.

During local development, we use that suffix, so your stories in storybook will use is like this:

<tttx-button_localcomponent>I am the latest version!</tttx-button_localcomponent>

When we build them for NPM, we run another step that inserts the version number.

yarn crowbar

This produces a /dist folder with the components with the current version number as specified in the package.json.

This is the version that is sent to NPM during the deployment pipeline.