oakd

oakd React Component Library

A scalable and efficient TypeScript React component library for modern applications.

📦 Installation

To start using oakd, install it via npm:

npm install oakd  

Then, import the styles in your App.tsx (or wherever you use oakd components):

import 'oakd/build/index.css';  

📌 Usage Example

After installation, use components like:

import React from "react";  
import 'oakd/build/index.css';  
import { Title, Paragraph } from "oakd";  

const App = () => (  
  <div className="app-container">  
    <Title>Hello from oakd</Title>  
    <Paragraph>Some content</Paragraph>
  </div>  
);  

export default App;  

🖌 Icon Pack & Generation

The oakd icon pack is custom-designed for OakFrame. All SVG icons are stored in the src/Icon/asset/ folder. Follow these steps to update or add icons:

• Add or update SVG files:
  Place your SVG files in the src/Icon/asset/ directory. File names should follow this pattern:

  oakd_Icon[A-Z][a-z+].svg
  

• Run the icon generation script:
  Use the following command to generate the icon exports:

  npm run icons
  

  This script creates a file named src/Icon/Icons.bin.tsx, which includes:

  • An iconMap object mapping icon names to components (e.g., { Angle: IAngle, Trash: ITrash }).
  • Individual icon components (e.g., IconTrash, IconUser, etc.).

• Icons are automatically included:
  Once the script runs, all icons are ready to use with proper paths and inlined assets.

🚀 Development

✅ Testing

Run all tests using Jest:

npm run test  

Jest is configured to:

• Use ts-jest for TypeScript support.
• Ignore node_modules/.
• Output coverage reports in the coverage/ directory.

📦 Building

Compile the library for production:

npm run build  

Rollup is configured to:

• Output both CommonJS (build/index.js) and ES modules (build/index.esm.js).
• Copy index.css to build/ automatically.
• Support image imports with @rollup/plugin-image.

📖 Storybook

Start a live-reloading Storybook instance:

npm run storybook  

Export Storybook as static files:

npm run storybook:export  

Serve the generated storybook-static/ folder.

✨ Generating New Components

Easily scaffold a new component using:

npm run generate YourComponentName  

This generates:

/src/YourComponentName  
  ├── YourComponentName.tsx  
  ├── YourComponentName.mdx
  ├── YourComponentName.stories.tsx  
  ├── YourComponentName.test.tsx  
  ├── YourComponentName.types.ts  
  ├── YourComponentName.css  

Modify templates under util/templates as needed.
Don’t forget to export your new component in index.ts!

🔧 Linting & Formatting

The project uses ESLint with a configuration that:

• Enforces best practices for TypeScript and React.
• Uses Prettier (configured to use tabs).
• Ignores generated or binary files (e.g. *.bin.tsx) from coverage.

npm run lint

If you want to run the ESLint with fix:

npm run lint:fix

🔗 Installing Locally

To test oakd in another project (test-app) without publishing, run:

npm i --save ../oakd  

This adds an entry in package.json:

"dependencies": {  
  "oakd": "file:../oakd"  
}  

⚠ Common Issue: Invalid Hook Call

If you see:

Invalid hook call. Hooks can only be called inside the body of a function component.  

This likely means multiple versions of React are installed.
Fix it by linking React from the consuming app:

npm link ../test-app/node_modules/react  

Alternatively, configure Webpack as suggested here.

📦 Publishing

📤 Publishing to NPM

Ensure you're logged in:

npm login  

Update package.json with your NPM package name, then publish:

npm publish  

The "prepublishOnly": "npm run build" script ensures a fresh build before publishing.

🛠 Hosting via GitHub

Alternatively, push the built package to GitHub and install it via:

npm i --save git+https://github.com/arkamedus/oakd.git#branch-name  

or

npm i --save github:arkamedus/oakd#branch-name  

🎨 Styling

Importing Styles

Include the library’s styles in your project:

import 'oakd/build/index.css';  

Using CSS Variables

Utilize predefined CSS variables from variables.css:

.example-container {  
    color: var(--oakd-white);  
    background-color: var(--oakd-black);  
}  

More on CSS Variables.

🛠 Additional Features

🌙 Dark Mode Support

Automatically adapts to dark mode using:

@media (prefers-color-scheme: dark) { ... }  

Customization options are in src/index.css.

📦 CSS Preprocessor Support

Supports Sass, Less, Stylus via:

yarn add node-sass --dev  # Sass  
yarn add stylus --dev      # Stylus  
yarn add less --dev        # Less  

For CSS Modules, update rollup-config.js:

postcss({  
  modules: true  
})  

💅 Styled Components

See this branch for implementation.

📂 Code Splitting

Load components on demand:

import TestComponent from 'oakd/build/TestComponent';  

For setup, refer to this commit.

🖼 Image Importing

Image imports now work automatically without additional configuration. You can use:

import logo from "./logo.png";  
export const ImageComponent = () => <img src={logo} />;  

📜 JSON Importing

Install JSON plugin:

npm i -D @rollup/plugin-json  

Add it to rollup-config.js:

plugins: [json(), ...]  

Now you can import JSON files:

import data from "./some-data.json";  
export const JsonDataComponent = () => <div>{data.description}</div>;  

🔗 Resources & Links

• 📘 Storybook Docs
• ⚡ Rollup Plugins
• 🎨 CSS Variables
• 💅 Styled Components

🤝 Contributing

We welcome contributions! Open an issue or submit a PR to improve oakd.
For detailed contribution guidelines, refer to our Contributing Guide.

📣 Join the Discussion

Have questions or ideas? Feel free to reach out on GitHub Discussions or open an issue! 🚀