This is a React Typescript components library which supports React and Next applications produced by Oak National Academy. A Storybook for the components can be found here please consult 1Password for access.
This library is suitable for use in an app using React 18 and Next.js 13.5+
You can install it using npm i @oaknational/oak-components or any other package manager that supports the NPM registry.
For components to be styled correctly they will need access to a theme, some global styles and the Lexend font.
You can add those to your app using something like:
import { OakThemeProvider, oakDefaultTheme } from "@oaknational/oak-components";
import Head from "next/head";
import { Lexend } from "next/font/google";
const lexend = Lexend({ subsets: ['latin'] });
export default function RootLayout({ children }) {
return (
<html lang="en">
<Head>
<OakGlobalStyles />
</Head>
<body className={lexend.className}>
<OakThemeProvider theme={oakDefaultTheme}>{children}</OakThemeProvider>
</body>
</html>
);
}If you're using TypeScript you might want to add @types/styled-components to your development dependencies (npm i -D @types/styled-components). This will ensure that all components are properly type hinted in your IDE.
- Copy the example env config
cp .env.example .env - Ask a colleague for the values to populate
.env - run
nvm use - run
npm install - To view the storybook run
npm run storybook
We use conventional commits and semantic versioning. Releases are managed by Semantic Release and are automatically published to NPM on every merge to main.
Changes should go through a pull-request to main and require approval by at least 1 reviewer. You should seek reviews from a QA/designer/PM when necessary.
Sometimes it isn't enough to develop entirely inside Storybook and it might be necessary to try local changes inside a target app. You can do this with yalc
- Install yalc
npm i yalc -g - Run
npm run publish:localto add the package to yalc's local registry. - Inside the target app run
yalc add @oaknational/oak-components— this will install the package from the local registry like it would from NPM- 🚨 if you're an Oak engineer developing in OWA there is a convenience script and you should use
npm run use-local-componentsinstead as it will perform some additional work to remove any existing installation of the package.
- 🚨 if you're an Oak engineer developing in OWA there is a convenience script and you should use
- Now when you start your target app you should have access to the locally packaged version of the library
- To uninstall the local package you can run
yalc remove @oaknational/oak-componentsinside the target app- 🚨 if you're an Oak engineer developing in OWA there is a convenience script and you should use
npm run remove-local-componentsinstead as it will automatically re-install the library from NPM.
- 🚨 if you're an Oak engineer developing in OWA there is a convenience script and you should use
We're trying to follow the tenets of "Atomic design". Brad Frost's book is a great resource if you're just starting out building your first component for this library. It's also a great reference if you're in doubt as to where a component belongs (it can be a little fuzzy at times!).
Components are organised into a three tier hierarchical structure applying the following rules:
- Can import other atoms
- Imports from molecules and organisms are forbidden!
- Generic
- Unstyled
- Avoid embedded logic and state
- No sub-components
(eg.
Box)
- Imports from atoms components and other molecules
- Imports from organisms are forbidden!
- Generic
- Styled
- Avoid embedded logic and state
- No sub-components
(eg.
IconButton)
-
Imports from atoms, molecules and occasionally organisms
-
Combines multiple molecules together
-
Applicable to a limited range of contexts which might occur in multiple apps
-
Styled
-
May contain embedded logic or state
-
May be split into sub-components (eg.
SchoolInputForm)NB. these rules are a work in progress. Modifications may be required as the library builds.