Installation

Setting up Neighborhood takes four steps: give your project access to the private packages, install them, load one stylesheet, and register the components you use. For a complete example from start to finish, see Quick start.

1. Add the package token

Neighborhood packages are private and hosted on GitHub Packages, so your project needs a token to install them. Request the Neighborhood token from IT Digital. Request package access lists what to include.

Add the token to the .npmrc file in the root of your project. If the project doesn’t have one, create it.

@fbin-web:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=[NBHD_TOKEN]

Replace [NBHD_TOKEN] with the token you’re given.

To keep the token out of source control, reference an environment variable instead, and set NBHD_TOKEN on your machine and in your build environment:

@fbin-web:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NBHD_TOKEN}

2. Install the packages

Install the set that matches your project.

Web Components on a brand site

npm install @fbin-web/neighborhood-core @fbin-web/neighborhood-brands

React or Next.js on a brand site

npm install @fbin-web/neighborhood-core @fbin-web/neighborhood-react @fbin-web/neighborhood-brands

Neighborhood React needs React 18 or later.

Without a brand

npm install @fbin-web/neighborhood-core @fbin-web/neighborhood-tokens

3. Load a stylesheet

Components read every color, font and spacing value from tokens, so each page needs one Neighborhood stylesheet. Without it, components render unstyled.

Brand stylesheets live in @fbin-web/neighborhood-brands/dist/<brand>/:

Use the all.css file. It includes the brand’s tokens and fonts. If your site already loads the brand fonts itself, load the brand’s tokens only, from @fbin-web/neighborhood-tokens/dist/brands/neighborhood.tokens.<brand>.css. Your fonts must use the same family names and weights as the brand.

Without a brand, load @fbin-web/neighborhood-tokens/dist/neighborhood.tokens.css.

With a bundler

Vite, Next.js, webpack and similar tools can import the stylesheet straight from the package:

import '@fbin-web/neighborhood-brands/dist/moen/neighborhood.moen.all.css';

Without a bundler

Copy the brand’s whole folder into your site’s assets and link the stylesheet in the <head>. Copy the entire folder, not just the CSS file: some brands load their fonts from the fonts/ folder next to the stylesheet.

<link
  rel="stylesheet"
  href="/assets/neighborhood/moen/neighborhood.moen.all.css" />

4. Register components

Importing a component registers its custom element, so its tag works anywhere on the page.

Web Components

Import the components you use:

import { NbhdButton, NbhdText } from '@fbin-web/neighborhood-core';

Or register every component at once:

import '@fbin-web/neighborhood-core';

Without a bundler, load the self-contained bundle with a script tag instead. Copy @fbin-web/neighborhood-core/build/library/neighborhood.js into your site’s assets and add it to the <head>:

<script
  type="module"
  src="/assets/neighborhood/neighborhood.js"></script>

Use the file in build/library/, not the one in dist/. The dist/ files expect a bundler and won’t run from a script tag on their own.

Then use them in your HTML:

<nbhd-text>Neighborhood Text Component</nbhd-text>
<nbhd-button variant="primary">Shop faucets</nbhd-button>

React

Import components from the React package. They render the same custom elements, so they look and behave the same as the Web Components.

import { NbhdButton, NbhdText } from '@fbin-web/neighborhood-react';

export function Promo() {
  return (
    <>
      <NbhdText>Neighborhood Text Component</NbhdText>
      <NbhdButton variant="primary">Shop faucets</NbhdButton>
    </>
  );
}

Neighborhood components run in the browser. In the Next.js App Router, render them from Client Components: files that start with 'use client'. Platform setup covers Next.js in more detail, and React covers props, events and forms.

For Vue, Svelte or Angular, use the Web Components; Platform setup covers each one.

TypeScript

Types are exported from the package root, alongside the components. With React, import them from the React package:

import type { ButtonProps, CardContent, Surface } from '@fbin-web/neighborhood-react';

Without React, import them from core:

import type { CardContent, Surface } from '@fbin-web/neighborhood-core';

Import from the package root only. Paths inside dist/ and types/ aren’t part of the public API and won’t resolve.

Browser support

Neighborhood uses modern CSS, including relative color syntax. It supports Chrome 119, Safari 16.4, Firefox 128 and later versions.

Check that it works

Add a primary button to a page:

<nbhd-button variant="primary">Shop faucets</nbhd-button>

If it shows your brand’s colors and font, you’re set. If it renders as plain text, the component isn’t registered. If it renders as a plain, unstyled button, the stylesheet didn’t load. You can compare against the same button in Storybook with your brand selected, and Troubleshooting covers other problems.

Next steps

• Working with tokens: use the same tokens as the components in your own CSS.
• Styling: customize a component without overriding it.
• Components: browse every component with its properties, slots and events.
• AI tools (MCP): let your AI assistant build with Neighborhood.