feat(ui): add ui-components package

[avivkeller]

@node-core/ui-components

Overview

This PR introduces the @node-core/ui-components package, which centralizes generic UI components used across the website. Previously, these components were located in apps/site/components/{Common,Containers}.

What Has Changed?

1. Generic UI components have been migrated to @node-core/ui-components.
2. Website-specific components remain in apps/site/components/{Blog,Downloads} as they are tailored for the website.
3. MDX components were not moved.

Implementation Details

Prop-Drilling Strategy

To keep @node-core/ui-components framework-agnostic, it does not rely on Next.js. However, many components on the website do depend on Next.js for functionalities such as routing and translations.

To maintain this separation, Next.js-specific dependencies are passed via props instead of being accessed directly within components.

Example: Migrating a Next.js-dependent Component

Original implementation in apps/site:

const Component: FC<...> = (...) => {
  const pathname = usePathname();
  const t = useTranslations();

  return <... ariaLabel={t('my.key')}></...>;
};

New implementation:

• Base component in @node-core/ui-components (agnostic version)

  const BaseComponent: FC<...> = ({ pathname, ariaLabel }) => {
    return <... ariaLabel={ariaLabel} pathname={pathname}></...>;
  };

• Wrapper component in apps/site (Next.js dependencies injected as props)

  const Component: FC<...> = (...) => {
    const pathname = usePathname();
    const t = useTranslations();

    return <BaseComponent pathname={pathname} ariaLabel={t('my.key')} />;
  };

How to Use These Components?

• When prop-drilling is required, import the component from apps/site.
• When prop-drilling is not needed, import it directly from @node-core/ui-components/<path/to/component>.

This ensures that @node-core/ui-components remains decoupled from Next.js while still allowing seamless integration with the website.

---

Storybook Integration

• Storybook is no longer a dependency of apps/site. Instead, it is now a (dev) dependency of @node-core/ui-components.
• The __design__ stories have been moved
• Story files for components that were moved are still available in @node-core/ui-components.
• For components that were not transferred, their Storybook stories have been removed.
  • To preview these components, run npm run dev or check the stories of components they depend on.

---

Tailwind Configuration

Tailwind remains a dependency in both apps/site and @node-core/ui-components. However, the Tailwind configuration has been centralized within @node-core/ui-components.

Key Changes:

• The Tailwind configuration now resides solely in @node-core/ui-components.
• It is re-exported in apps/site, so no additional configuration is needed in apps/site.
  • Future updates to Tailwind (e.g., Tailwind v4) will allow direct imports via the @config variable in the CSS file, removing the need to re-export

Known Issue: Font Configuration

• Currently, the Tailwind configuration assumes that fonts are set via CSS variables:
  • --font-open-sans
  • --font-ibm-plex-mono
• This approach is not ideal because it relies on Next.js’s font loading system.
• A TODO comment has been added, suggesting a move away from this dependency.

---

Additional Changes

1. FNM Logo Update

   • The TODO regarding the FNM logo has been resolved.
   • The correct vector from @Schniz has been added.

2. CSS

   • All global styles from styles/ have been moved into @node-core/ui-components.
   • This change helps consolidate styles and avoid duplication across projects.

3. Logo Renames

   • Logos in the @node-core/ui-components package have new names:
     • Twitter -> X
     • Discord's default export was called Bluesky, it is now Discord.

---

Next Steps

While setting up @node-core/ui-components, two TODO comments were added for future improvements:

1. Navbar Styles Refactor (apps/site/withNavBar.tsx)

   • It now imports styles from @node-core/ui-components/Containers/NavBar/index.module.css.
   • However, importing styles this way isn’t ideal, and a TODO comment has been added.

2. Tailwind Font Configuration

   • As mentioned earlier, font settings currently depend on Next.js’s font loading system.
   • A TODO comment suggests moving away from this dependency to keep @node-core/ui-components fully framework-agnostic.

---

Requests for Reviewers

1. .github/workflows/lint-and-tests.yml has been updated to reflect this change. Could someone verify that the changes were correct?

---

TL;DR

✅ Moves generic UI components to @node-core/ui-components
✅ Moves Storybook dependency from apps/site to @node-core/ui-components
✅ Removes Storybook stories for non-migrated components
✅ Centralizes Tailwind configuration
✅ Moves global styles into the new package
✅ Updates FNM logo with the correct vector
🔜 Future work needed on two TODO comments

Thank you all for being patient over the past few months as this slowly comes together.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
nodejs-org	✅ Ready (Inspect)	Visit Preview	Mar 22, 2025 1:21pm

[AugustinMauroy]

@AugustinMauroy If you want to get a head start, feel free to submit a PR into this branch with the new test runner. There's no rush—this isn't a priority right now.

No need to rush. Jest still work. Also we need to work step by step.

Pull Request Overview

This PR migrates generic UI components from the website codebase to a new, centralized package (@node-core/ui-components) while updating related documentation, workflows, and Storybook configurations. Key changes include:

• Migrating and updating component imports (e.g. ActiveLink, Preview, icons) to use @node-core/ui-components.
• Updating documentation (COLLABORATOR_GUIDE.md) and workflows (.github/workflows/lint-and-tests.yml) to reflect the new package structure.
• Removing legacy Storybook configurations and unused component stories from apps/site.

Reviewed Changes

Copilot reviewed 290 out of 296 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
apps/site/components/Common/ActiveLink.tsx	Updated to wrap the generic BaseActiveLink from the new @node-core/ui-components pkg.
COLLABORATOR_GUIDE.md	Documentation updated to reference the new package and file locations.
.github/workflows/lint-and-tests.yml	Workflow now targets packages/ui-components for building Storybook and coverage.
apps/site/app/[locale]/layout.tsx	Updated global styles import to use the centralized Tailwind configuration.
apps/site/app/[locale]/next-data/og/[category]/[title]/route.tsx	Icon imports updated to use components from @node-core/ui-components.
apps/site/components/Blog/BlogPostCard/index.tsx	Updated the Preview component import to reference the new package location.
apps/site/components/Blog/BlogPostCard/tests/index.test.mjs	Adjusted BlogPostCard import to reflect file movement within apps/site.
apps/site/.storybook/main.ts	Removed Storybook configuration, in favor of the configuration now in the new package.
apps/site/components/Blog/BlogHeader/index.stories.tsx	Removed legacy Storybook stories corresponding to migrated components.
apps/site/components/Common/AvatarGroup/*	Removed Avatar, AvatarGroup, and related Storybook files as they’re no longer needed.

Files not reviewed (6)

• apps/site/.stylelintignore: Language not supported
• apps/site/components/Common/AvatarGroup/Avatar/index.module.css: Language not supported
• apps/site/components/Common/AvatarGroup/Overlay/index.module.css: Language not supported
• apps/site/components/Common/Badge/index.module.css: Language not supported
• apps/site/components/Common/Banner/index.module.css: Language not supported
• apps/site/components/Common/Blockquote/index.module.css: Language not supported

[avivkeller]

What?! A successful deployment on the first try?! Woo!

[github-actions]

Lighthouse Results

URL	Performance	Accessibility	Best Practices	SEO	Report
/en	🟢 99	🟢 100	🟢 100	🟢 91	🔗
/en/about	🟢 100	🟢 100	🟢 100	🟢 91	🔗
/en/about/previous-releases	🟢 100	🟢 100	🟢 100	🟢 92	🔗
/en/download	🟠 89	🟢 100	🟢 100	🟢 91	🔗
/en/blog	🟢 100	🟢 100	🟢 96	🟢 92	🔗

[avivkeller]

Storybook failed to deploy because storybook has been moved in this PR, could a repo admin manually deploy and test? Thanks!

[ovflowd]

Since this PR updated the workflow for the new package, I added a workflow_dispatch trigger to run the modified workflow manually. (As the pull_request_target trigger is setup to only run on the main branch)

Ah I see, please remove that afterwards.

[ovflowd]

I went through all the code. Took me a while. I just wanted to thank you for the massive work done here! It is immensively appreciated, Aviv :)

[avivkeller]

Ah I see, please remove that afterwards.

Yep, will do! That'll be the last thing done, as (as you can see above) the storybook won't deploy unless via that manual trigger.

[avivkeller]

Manually deployed workflow

View Storybook / Check Chromatic Tests

Tests

@nodejs/website

Metric	Passed	Total
Test Suites	34	34
Tests	157	157
Snapshots	0	0
Execution Time	6.49s

Coverage: 87%

@node-core/ui-components

Metric	Passed	Total
Test Suites	8	8
Tests	24	24
Snapshots	0	0
Execution Time	5.129s

Coverage: 95%

[avivkeller]

@ovflowd I've addressed your reviews. This PR passes all tests and lints, but it requires a manual merge because the workflow for running Storybook has changed in this PR, and the old workflow isn't compatible with this package.

[avivkeller]

Unless someone objects, I'm planning to merge this at the end of the day (UTC-4) on Monday (let's say around 8pm). That should give reviewers time to take a look and object if need be. Feel free to 👎 this comment, and I'll wait longer.

[ovflowd]

@ovflowd I've addressed your reviews. This PR passes all tests and lints, but it requires a manual merge because the workflow for running Storybook has changed in this PR, and the old workflow isn't compatible with this package.

All good. Feel free to do a manual merge, or ping me if blocked.

[avivkeller]

I'm not quite sure how one would install this package outside the monorepo (i.e. from api-docs-tooling). IIRC you can't import from subdirectories within git repository. Are we planning to publish to npm?

[ovflowd]

I'm not quite sure how one would install this package outside the monorepo (i.e. from api-docs-tooling). IIRC you can't import from subdirectories within git repository. Are we planning to publish to npm?

I do believe we can provide git paths within the npm install command

[avivkeller]

Per npm/npm#2974 (comment):

this isn't something that the npm CLI team is interested in adding to the tool

Third-party tools like GitPkg allow you to do this, but I'm not sure how we feel about using a third-party tool for installing dependencies.

However, both yarn (yarnpkg/yarn#4725 (comment)) and pnpm (pnpm/pnpm#7487) support this. We would need to convert api-docs-tooling to a yarn or pnpm project, which would mean that any project installing it would also need yarn / pnpm, and I'm not how core will feel about using something other than npm for api generation

(Although maybe this is an issue for api-docs-tooling)

[avivkeller]

I've opened nodejs/api-docs-tooling#236 for further discussion.