@near-pagoda/ui NPM

NEAR/Pagoda UI

A React component library that implements the official design system of NEAR and Pagoda. Feel free to open up new issues for any bugs that you run into or any features/components you'd like to see implemented.

Required Peer Dependencies

React 18

Zustand 4 - Our openToast() method is able to work in any context due to relying on a Zustand global store.

Installation & Setup

pnpm add zustand
pnpm add @near-pagoda/ui

In your root layout.tsx file, wrap your application with the <PagodaUiProvider> and pass in your framework's <Link> component and router methods. You'll also want to include the <Toaster /> component to display toasts when calling openToast().

'use client';

import '@near-pagoda/ui/styles.css';

import Link from 'next/link';
import { useRouter } from 'next/navigation';
import { PagodaUiProvider, Toaster } from '@near-pagoda/ui';

/*
  The suppressHydrationWarning on <html> is required by next-theme's <ThemeProvider>:
  https://github.com/pacocoursey/next-themes?tab=readme-ov-file#with-app
*/

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <meta
          name="viewport"
          content="width=device-width, initial-scale=1, minimum-scale=1"
        />
      </head>

      <body>
        <PagodaUiProvider
          value={{
            Link,
            useRouter
          }}
        >
          <Toaster />
          <main>{children}</main>
        </PagodaUiProvider>
      </body>
    </html>
  );
}

Why is <PagodaUiProvider> needed? Some of our components render anchor tags or dynamically change the current route. This provider allows our library to support any React framework (Vanilla/Vite, Next JS, etc) by passing in your router's components and hooks. It also supports dark/light mode and opts into the user's preferred theme via next-theme.

Documentation

Please refer to README.md files in src/components for examples and documentation of components.

Contributing

This project requires pnpm version 9.1.1. The strict version requirement will help keep our lockfile consistent as more developers contribute. Make sure you have the correct version of pnpm installed:

pnpm -v # This should output 9.1.1
npm install -g pnpm@9.1.1 # Install the correct version if needed

Run these commands to begin local development and watch for changes:

pnpm dev
pnpm test:watch

Create a branch off of main
Test your local changes
Push a PR for review

NOTE: A development preview environment for the component library will be developed soon: https://github.com/near/pagoda-ui/issues/6

Test Local Changes

Follow these steps to preview local changes to the UI library within any project that depends on the library:

Have your project and the UI library cloned as siblings. EG: projects/cool-project and projects/pagoda-ui.
Inside pagoda-ui, run pnpm dev.
Inside your project folder, run pnpm add file:../pagoda-ui.
After making any changes to pagoda-ui, you will need to restart your project's development server for the component changes to appear locally within your project.
Once you're done testing changes, make sure you revert the changes in your project's package.json and lock file so that you're no longer referencing the local file protocol (eg: file:../pagoda-ui).

NOTE: Due to this library having peer dependencies, pnpm link isn't compatible - that's why we have to rely on using file: instead.

Viewing Package Statistics

After you've run pnpm build or pnpm dev, a stats.html file will be generated to show a visual breakdown of the size of the library based on source code and dependencies. You can open this in your browser by running:

open ./stats.html

This can be helpful to catch or debug a dependency that might have bloated the package size.

Publishing a Release

Merge all desired changes into main via pull requests.
Determine the version number for the new release.
Push updated version field in package.json to main.
Create a new release via GitHub: https://github.com/near/pagoda-ui/releases/new
Use updated version value as the new tag and Release title value and use main as the target branch.
Click the publish button.
A GitHub workflow will kick off to automatically publish a new version to NPM: https://github.com/near/pagoda-ui/actions/workflows/publish-to-npm.yml
The new version number published to NPM will be driven by the value in package.json.
Confirm published changes by visiting package: https://www.npmjs.com/package/@near-pagoda/ui