Platform setup

Neighborhood works the same way on every platform. Each page needs three things:

1. The components, from the core package or its self-contained bundle.
2. One brand stylesheet, with its fonts.
3. Markup that places the components and fills their slots with content.

What changes from platform to platform is how those files reach the page and how content gets into the markup. Installation covers the packages and files; this page covers each platform.

With a bundler or without

The build/library/neighborhood.js file is self-contained, so it runs from a script tag with nothing else installed. Brand stylesheets load their fonts from a fonts/ folder next to them, so copy the brand’s whole folder, not just the CSS file.

Next.js

1. Install the React, core and brands packages, as in Installation.

2. Import the brand stylesheet once, in your root layout or global CSS:

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

3. Render Neighborhood components from Client Components. They depend on the browser, so files that use them start with 'use client':

   'use client';
   
   import { NbhdCta, NbhdHeadlineContent, NbhdText } from '@fbin-web/neighborhood-react';
   
   export function Intro() {
     return (
       <NbhdHeadlineContent>
         <NbhdText slot="title" tag="h1" variant="title">Faucets made for everyday</NbhdText>
         <NbhdCta slot="cta" href="/faucets">Shop faucets</NbhdCta>
       </NbhdHeadlineContent>
     );
   }

4. Put text and media in slots rather than props. Slotted content is in the server-rendered HTML, so it shows before the components load and is visible to search engines. Props are applied once the components load in the browser.

No changes to next.config are needed.

React with Vite

Install the React, core and brands packages, import the brand stylesheet in your app’s entry file, and import components from @fbin-web/neighborhood-react. Quick start walks through it from a new project.

Static sites and Eleventy

Copy the files from node_modules into your site’s output, then reference them in your page layout. In Eleventy, passthrough copy does this on every build:

// eleventy.config.js
eleventyConfig.addPassthroughCopy({
  './node_modules/@fbin-web/neighborhood-core/build/library/neighborhood.js': 'js/neighborhood.js',
  './node_modules/@fbin-web/neighborhood-brands/dist/moen': 'css/moen',
});

<head>
  <link rel="stylesheet" href="/css/moen/neighborhood.moen.all.css" />
  <script type="module" src="/js/neighborhood.js"></script>
</head>

Other static site generators work the same way: copy the bundle and the brand folder, then link them.

Shopify

Shopify themes have no bundler, so use the self-contained files.

1. Upload the assets. Add build/library/neighborhood.js and the brand’s token file (neighborhood-tokens/dist/brands/neighborhood.tokens.<brand>.css) to the theme’s assets folder.

2. Load them in the layout. Add this before the closing </head> in each layout that uses Neighborhood:

   <script type="module" src="{{ 'neighborhood.js' | asset_url }}"></script>
   <link rel="stylesheet" href="{{ 'neighborhood.tokens.moen.css' | asset_url }}">

3. Load the brand fonts. Shopify’s assets folder is flat, so the brand’s font files can’t keep their fonts/ folder. Upload the font files to assets, and load them with a font stylesheet saved as a .css.liquid file that points to each font with asset_url.

4. Build sections from components. In each section, settings become component attributes and text settings fill slots:

   <nbhd-headline-content surface="{{ section.settings.surface }}">
     <nbhd-text slot="title" tag="h2" variant="title">{{ section.settings.title }}</nbhd-text>
     <nbhd-cta slot="cta" href="{{ section.settings.cta_url }}">{{ section.settings.cta_label }}</nbhd-cta>
   </nbhd-headline-content>

   Repeating content, such as the cards in a Card List, becomes section blocks, with one component for each block.

Bloomreach

In Bloomreach, each Neighborhood component becomes a content type plus a component definition, following the content model:

• Slots become content type fields. Eyebrows and titles are text fields, body copy is rich text, calls to action share a CTA field group, and images and video share a media field group.
• Properties become component parameters. Booleans become toggles and fixed-value properties such as surface become dropdowns.
• Repeating content, such as cards in a Card List, becomes a repeatable field group with its own content type.

Neighborhood can generate these content type and component definitions for any component. Request them for the components your site uses.

Power Pages

Power Pages has no bundler, so use the self-contained files:

1. Upload build/library/neighborhood.js and the brand’s stylesheet as web files. Keep the brand’s font files at the paths the stylesheet expects, or use the brand’s token file (neighborhood-tokens/dist/brands/neighborhood.tokens.<brand>.css) and load the fonts separately.
2. Reference both files in the <head> of your site’s header template.
3. Write component markup in your page templates, filling slots with your page content.

More detailed Power Pages notes are coming. If you’re setting up a Power Pages site now, get in touch.

Other libraries on the page

Neighborhood components keep their styles inside a shadow DOM, so other CSS on the page, such as Bootstrap, Tailwind or a theme’s own styles, can’t change their internals. Page-wide styles can still affect the content you put in slots, because that content is part of your page. If a library’s styles change how slotted text or links look, scope the library’s styles away from Neighborhood sections, and mention the library when you report a bug.