React setup | Get started

Install SWAN

Configuring the .npmrc file for your project

SWAN is hosted in a private npm repository, so to install the package, you need to ensure that your .npmrc file is configured.

Add an .npmrc file to the root of our project with the following content.

.npmrcGetting artifactory token

@vp:registry=https://vistaprint.jfrog.io/vistaprint/api/npm/npm/
@vistaprint:registry=https://vistaprint.jfrog.io/vistaprint/api/npm/npm/
//vistaprint.jfrog.io/vistaprint/api/npm/npm/:_authToken=${VP_ARTIFACTORY_TOKEN}
//vistaprint.jfrog.io/vistaprint/api/npm/npm/:always-auth=true

@vp:registry=https://vistaprint.jfrog.io/vistaprint/api/npm/npm/
@vistaprint:registry=https://vistaprint.jfrog.io/vistaprint/api/npm/npm/
//vistaprint.jfrog.io/vistaprint/api/npm/npm/:_authToken=${VP_ARTIFACTORY_TOKEN}
//vistaprint.jfrog.io/vistaprint/api/npm/npm/:always-auth=true

# Login 
npm login --registry https://vistaprint.jfrog.io/artifactory/api/npm/npm/
# When asked username: firstname.lastname
# For passwoard Use API Key (Jfrog -> Edit Profile -> API Key)
# For email: use your official email id
# Copy the token from ./.npmrc file and store in the env file

# Login 
npm login --registry https://vistaprint.jfrog.io/artifactory/api/npm/npm/
# When asked username: firstname.lastname
# For passwoard Use API Key (Jfrog -> Edit Profile -> API Key)
# For email: use your official email id
# Copy the token from ./.npmrc file and store in the env file

You need to configure the VP_ARTIFACTORY_TOKEN environment variable in your system. To retrieve the value, please log in to jfrog and configure your npm client by login into it.

Read more in detail at "Install NPM Packages from Vistaprint Artifactory"

Install the latest version of SWAN

Peer Dependency
- react: >=17 <19 (Preferred version ^18.3.0)
- react-dom: >=17 <19 (Preferred version ^18.3.0)

shpackage.json

npm i @vp/swan@latest

npm i @vp/swan@latest

{
  "name": "your-project",
  "devDependencies": {
    "@types/react": "18.0.34",
    "@types/react-dom": "18.0.11",
  },
}

{
  "name": "your-project",
  "devDependencies": {
    "@types/react": "18.0.34",
    "@types/react-dom": "18.0.11",
  },
}

For Library Owners

The library only needs @vp/swan for dev dependency and should keep it as a peer dependency in their package.json.

You are not required to do the below setup for your library, but if you do have an example/sample application, you need to configure based on the type of sample application you have.

Project setup

Setup with popular frameworks like Create React App (CRA), Gatsby, and Next.js.

Getting Started With Gatsby < 4.19

Since previous versions of Gatsby don't come with Head API we will need to use Helmet.

SwanConfiguration configures the SWAN provider using react-helmet-async, since Gatsby doesn't come with any head management toolkit.
gatsby-ssr.js wrapRootElement wraps the SwanConfiguration for all the pages during SSR mode.
gatsby-browser.js wrapRootElement wraps the SwanConfiguration for all the pages in the browser.
gatsby-config.js: You need to add the gatsby plugin for react-helmet.
Layout gives an overall pattern for the page, along with skip links for accessibility support.
Install react-helmet-async and gatsby-plugin-react-helmet for this setup to work.

# After bootstraping Gatsby project & installing @vp/swan
npm i react-helmet-async gatsby-plugin-react-helmet
npm i @types/react-helmet-async --save-dev

# After bootstraping Gatsby project & installing @vp/swan
npm i react-helmet-async gatsby-plugin-react-helmet
npm i @types/react-helmet-async --save-dev

import * as React from 'react'
import { Helmet } from 'react-helmet-async'
import { Link } from 'gatsby'
import {
  SwanProvider,
  SwanHead,
  SWAN_STYLE_KEY_MAP,
  SWAN_BASE_URL_MAP,
  useBrowserClasses,
  getRootClassNames,
} from '@vp/swan'

const styleKeys = [
  SWAN_STYLE_KEY_MAP.button,
  SWAN_STYLE_KEY_MAP.accordion,
  // List all the required keys, Doesn't autoload keys now
]

export const SwanConfiguration: React.FC<unknown> = ({ children }) => {
  const browserClassName = useBrowserClasses()
  const bodyClassName = getRootClassNames()
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementatoin will vary
  return (
    <SwanProvider
      swanTenant={tenant}
      swanLocale={locale}
      globalLinkComponent={Link}
    >
      <Helmet
        htmlAttributes={{ class: browserClassName }}
        bodyAttributes={{ class: bodyClassName }}
      />
      <SwanHead
        renderWith={Helmet}
        renderStyleContentAsChildren
        styleSheetKeys={styleKeys}
      />
      {/* Optionally, if you need, wrap ScreenProvider at this level */}
      {children}
    </SwanProvider>
  )
}

import * as React from 'react'
import { Helmet } from 'react-helmet-async'
import { Link } from 'gatsby'
import {
  SwanProvider,
  SwanHead,
  SWAN_STYLE_KEY_MAP,
  SWAN_BASE_URL_MAP,
  useBrowserClasses,
  getRootClassNames,
} from '@vp/swan'

const styleKeys = [
  SWAN_STYLE_KEY_MAP.button,
  SWAN_STYLE_KEY_MAP.accordion,
  // List all the required keys, Doesn't autoload keys now
]

export const SwanConfiguration: React.FC<unknown> = ({ children }) => {
  const browserClassName = useBrowserClasses()
  const bodyClassName = getRootClassNames()
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementatoin will vary
  return (
    <SwanProvider
      swanTenant={tenant}
      swanLocale={locale}
      globalLinkComponent={Link}
    >
      <Helmet
        htmlAttributes={{ class: browserClassName }}
        bodyAttributes={{ class: bodyClassName }}
      />
      <SwanHead
        renderWith={Helmet}
        renderStyleContentAsChildren
        styleSheetKeys={styleKeys}
      />
      {/* Optionally, if you need, wrap ScreenProvider at this level */}
      {children}
    </SwanProvider>
  )
}

import { GatsbyBrowser } from 'gatsby'
import React from 'react'
import { SwanConfiguration } from './src/components/SwanConfiguration'

export const wrapRootElement: GatsbyBrowser['wrapRootElement'] = ({
  element,
}) => {
  return <SwanConfiguration>{element}</SwanConfiguration>
}

import { GatsbyBrowser } from 'gatsby'
import React from 'react'
import { SwanConfiguration } from './src/components/SwanConfiguration'

export const wrapRootElement: GatsbyBrowser['wrapRootElement'] = ({
  element,
}) => {
  return <SwanConfiguration>{element}</SwanConfiguration>
}

import { GatsbySSR } from 'gatsby'
import React from 'react'
import { SwanConfiguration } from './src/components/SwanConfiguration'

export const wrapRootElement: GatsbySSR['wrapRootElement'] = ({ element }) => {
  return <SwanConfiguration>{element}</SwanConfiguration>
}

import { GatsbySSR } from 'gatsby'
import React from 'react'
import { SwanConfiguration } from './src/components/SwanConfiguration'

export const wrapRootElement: GatsbySSR['wrapRootElement'] = ({ element }) => {
  return <SwanConfiguration>{element}</SwanConfiguration>
}

module.exports = {
  plugins: [
    'gatsby-plugin-react-helmet',
    // other plugins
  ],
  // other configs
}

module.exports = {
  plugins: [
    'gatsby-plugin-react-helmet',
    // other plugins
  ],
  // other configs
}

import {
  SiteMain,
  SiteContent,
  MainContentStart,
  BoundedContent,
  SkipLink,
} from '@vp/swan'
import * as React from 'react'

export const Layout: React.FC<unknown> = () => {
  return (
    <SiteContent>
      <SkipLink>Skip to main content</SkipLink>
      <header>Page Header & Navigation</header>
      <SiteMain>
        <MainContentStart />
        <BoundedContent>Your Site Content</BoundedContent>
      </SiteMain>
    </SiteContent>
  )
}

import {
  SiteMain,
  SiteContent,
  MainContentStart,
  BoundedContent,
  SkipLink,
} from '@vp/swan'
import * as React from 'react'

export const Layout: React.FC<unknown> = () => {
  return (
    <SiteContent>
      <SkipLink>Skip to main content</SkipLink>
      <header>Page Header & Navigation</header>
      <SiteMain>
        <MainContentStart />
        <BoundedContent>Your Site Content</BoundedContent>
      </SiteMain>
    </SiteContent>
  )
}

Getting Started With Gatsby >= 4.19

The latest version of gatsby comes with its own Head management toolkit.

In Summary, all the pages and templates should return a named component called Head which should modify everything in Head. This will receive the data and pageContext that the default component receives.

Additionally, to modify attributes on html or body tag, you need to use the appropriate methods inside onRenderBody (as shown below). Additionally, you could modify head within this as well which are common to all the pages.

Since this doesn't need helmet, you don't need to install helmet, or configure gatsby-config with react-helmet plugin.

Please refer to PageOrTemplate example on how to manage SEO

When rendering with SSR/SSG, your application should be wrapped in <SwanSSRProvider /> to avoid hydration issues.

SwanConfigurationgatsby-browser.tsxgatsby-ssr.tsxPageOrTemplate.tsx

import * as React from 'react'
import { Helmet } from 'react-helmet'
import { Link } from 'gatsby'
import { SwanProvider, SwanSSRProvider, useBrowserClasses } from '@vp/swan'

export const SwanConfiguration: React.FC<unknown> = ({ children }) => {
  const { tenant, locale } = getTenantAndLocale() // illustration function, actual implementation will vary
  useBrowserClasses(true) // Passing true, auto adds browser class to head, using Vanilla JS QuerySelector
  return (
    <SwanProvider
      swanTenant={tenant}
      swanLocale={locale}
      globalLinkComponent={Link}
    >
      <SwanSSRProvider>
        {/* Optionally, if you need, wrap ScreenProvider at this level */}
        {children}
      </SwanSSRProvider>
    </SwanProvider>
  )
}

import * as React from 'react'
import { Helmet } from 'react-helmet'
import { Link } from 'gatsby'
import { SwanProvider, SwanSSRProvider, useBrowserClasses } from '@vp/swan'

export const SwanConfiguration: React.FC<unknown> = ({ children }) => {
  const { tenant, locale } = getTenantAndLocale() // illustration function, actual implementation will vary
  useBrowserClasses(true) // Passing true, auto adds browser class to head, using Vanilla JS QuerySelector
  return (
    <SwanProvider
      swanTenant={tenant}
      swanLocale={locale}
      globalLinkComponent={Link}
    >
      <SwanSSRProvider>
        {/* Optionally, if you need, wrap ScreenProvider at this level */}
        {children}
      </SwanSSRProvider>
    </SwanProvider>
  )
}

import { GatsbyBrowser } from 'gatsby'
import React from 'react'
import { SwanConfiguration } from './src/components/SwanConfiguration'

export const wrapRootElement: GatsbyBrowser['wrapRootElement'] = ({
  element,
}) => {
  return <SwanConfiguration>{element}</SwanConfiguration>
}

import { GatsbyBrowser } from 'gatsby'
import React from 'react'
import { SwanConfiguration } from './src/components/SwanConfiguration'

export const wrapRootElement: GatsbyBrowser['wrapRootElement'] = ({
  element,
}) => {
  return <SwanConfiguration>{element}</SwanConfiguration>
}

import { GatsbySSR } from 'gatsby'
import React from 'react'
import { SwanConfiguration } from './src/components/SwanConfiguration'
import {
  SwanHead,
  SWAN_BASE_URL_MAP,
  SWAN_STYLE_KEY_MAP,
  getRootClassNames,
} from '@vp/swan'

const styleKeysToLoad = [SWAN_STYLE_KEY_MAP.button, SWAN_STYLE_KEY_MAP.icon]

export const onRenderBody: GatsbySSR['onRenderBody'] = ({
  setBodyAttributes,
  setHtmlAttributes,
  setHeadComponents,
  pathname,
}) => {
  const bodyClassNames = getRootClassNames()
  const { locale, tenant } = getLocaleAndTenant() // Illustration function. Actual implementatoin will vary
  setHtmlAttributes({
    lang: locale,
  })
  setHeadComponents([
    <SwanHead
      key="swan-head"
      swanTenant={tenant}
      swanLocale={locale}
      styleSheetKeys={styleKeysToLoad}
    />,
  ])

  setBodyAttributes({
    className: bodyClassNames,
  })
}

export const wrapRootElement: GatsbySSR['wrapRootElement'] = ({ element }) => {
  return <SwanConfiguration>{element}</SwanConfiguration>
}

import { GatsbySSR } from 'gatsby'
import React from 'react'
import { SwanConfiguration } from './src/components/SwanConfiguration'
import {
  SwanHead,
  SWAN_BASE_URL_MAP,
  SWAN_STYLE_KEY_MAP,
  getRootClassNames,
} from '@vp/swan'

const styleKeysToLoad = [SWAN_STYLE_KEY_MAP.button, SWAN_STYLE_KEY_MAP.icon]

export const onRenderBody: GatsbySSR['onRenderBody'] = ({
  setBodyAttributes,
  setHtmlAttributes,
  setHeadComponents,
  pathname,
}) => {
  const bodyClassNames = getRootClassNames()
  const { locale, tenant } = getLocaleAndTenant() // Illustration function. Actual implementatoin will vary
  setHtmlAttributes({
    lang: locale,
  })
  setHeadComponents([
    <SwanHead
      key="swan-head"
      swanTenant={tenant}
      swanLocale={locale}
      styleSheetKeys={styleKeysToLoad}
    />,
  ])

  setBodyAttributes({
    className: bodyClassNames,
  })
}

export const wrapRootElement: GatsbySSR['wrapRootElement'] = ({ element }) => {
  return <SwanConfiguration>{element}</SwanConfiguration>
}

import { graphql, HeadProps, PageProps } from 'gatsby'
import { FC } from 'react'

type QueryDataType = {
  pageData: {
    title: string
  }
}
type PageContext = {
  locale: string
  slug: string
}

const PageOrTemplate: FC<PageProps<QueryDataType, PageContext>> = () => {
  return <div>Page Content</div>
}

export default PageOrTemplate

export const Head: FC<HeadProps<QueryDataType, PageContext>> = data => {
  return (
    <>
      <title>{data.pageData.title}</title>
    </>
  )
}

export const query = graphql`
  query PageOrTemplateQuery {
    pageData: someGraphqlMethod(slug: {current: {eq: $slug}}) {
      title
    }
  }
`

import { graphql, HeadProps, PageProps } from 'gatsby'
import { FC } from 'react'

type QueryDataType = {
  pageData: {
    title: string
  }
}
type PageContext = {
  locale: string
  slug: string
}

const PageOrTemplate: FC<PageProps<QueryDataType, PageContext>> = () => {
  return <div>Page Content</div>
}

export default PageOrTemplate

export const Head: FC<HeadProps<QueryDataType, PageContext>> = data => {
  return (
    <>
      <title>{data.pageData.title}</title>
    </>
  )
}

export const query = graphql`
  query PageOrTemplateQuery {
    pageData: someGraphqlMethod(slug: {current: {eq: $slug}}) {
      title
    }
  }
`

Getting Started With NextJS

SwanConfiguration configures the SWAN provider using Head
_app.js wraps SwanConfiguration for every page.
Layout gives an overall pattern for the page, along with skip links for accessibility.

pages/_app.tsxpages/_document.tsxLayout.tsx

import { useBrowserClasses } from '@vp/swan'
import type { AppProps } from 'next/app'

export default function MyApp({ Component, pageProps }: AppProps) {
  useBrowserClasses(true)
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementation will differ
  return (
    <SwanProvider
      swanTenant={tenant}
      swanLocale={locale}
      globalLinkComponent={Link}
    >
      {/* When rendering with CSR, please remove the <SwanSSRProvider /> wrapper */}
      <SwanSSRProvider>
        <Component {...pageProps} />
      </SwanSSRProvider>
    </SwanProvider>
  )
}

import { useBrowserClasses } from '@vp/swan'
import type { AppProps } from 'next/app'

export default function MyApp({ Component, pageProps }: AppProps) {
  useBrowserClasses(true)
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementation will differ
  return (
    <SwanProvider
      swanTenant={tenant}
      swanLocale={locale}
      globalLinkComponent={Link}
    >
      {/* When rendering with CSR, please remove the <SwanSSRProvider /> wrapper */}
      <SwanSSRProvider>
        <Component {...pageProps} />
      </SwanSSRProvider>
    </SwanProvider>
  )
}

import {
  getRootClassNames,
  SwanHead,
  SwanProvider,
  SWAN_BASE_URL_MAP,
  SWAN_STYLE_KEY_MAP,
} from '@vp/swan'
import { Head, Html, Main, NextScript } from 'next/document'
import Link from 'next/link'

const styleKeys = [
  SWAN_STYLE_KEY_MAP.accordion,
  SWAN_STYLE_KEY_MAP.tabs,
  SWAN_STYLE_KEY_MAP.alertBox,
  SWAN_STYLE_KEY_MAP.button,
]
export default function Document() {
  const rootClassName = getRootClassNames()
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementation will vary.
  return (
    <Html lang="en">
      <Head>
        <SwanHead
          swanTenant={tenant}
          swanLocale={locale}
          styleSheetKeys={styleKeys}
        />
      </Head>
      <body className={rootClassName}>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

import {
  getRootClassNames,
  SwanHead,
  SwanProvider,
  SWAN_BASE_URL_MAP,
  SWAN_STYLE_KEY_MAP,
} from '@vp/swan'
import { Head, Html, Main, NextScript } from 'next/document'
import Link from 'next/link'

const styleKeys = [
  SWAN_STYLE_KEY_MAP.accordion,
  SWAN_STYLE_KEY_MAP.tabs,
  SWAN_STYLE_KEY_MAP.alertBox,
  SWAN_STYLE_KEY_MAP.button,
]
export default function Document() {
  const rootClassName = getRootClassNames()
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementation will vary.
  return (
    <Html lang="en">
      <Head>
        <SwanHead
          swanTenant={tenant}
          swanLocale={locale}
          styleSheetKeys={styleKeys}
        />
      </Head>
      <body className={rootClassName}>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

import {
  SiteMain,
  SiteContent,
  MainContentStart,
  BoundedContent,
  SkipLink,
} from '@vp/swan'
import * as React from 'react'
import Head from 'next/head'

type LayoutProps = {
  pageTitle: string
  pageDescription: string
}

export const Layout: React.FC<LayoutProps> = ({
  children,
  pageTitle,
  pageDescription,
}) => {
  return (
    <>
      <Head>
        <title>{pageTitle}</title>
        <meta name="description" content={pageDescription} />
      </Head>
      <SiteContent>
        <SkipLink>Skip to main content</SkipLink>
        <header>Page Header & Navigation</header>
        <SiteMain>
          <MainContentStart />
          <BoundedContent>{children}</BoundedContent>
        </SiteMain>
      </SiteContent>
    </>
  )
}

import {
  SiteMain,
  SiteContent,
  MainContentStart,
  BoundedContent,
  SkipLink,
} from '@vp/swan'
import * as React from 'react'
import Head from 'next/head'

type LayoutProps = {
  pageTitle: string
  pageDescription: string
}

export const Layout: React.FC<LayoutProps> = ({
  children,
  pageTitle,
  pageDescription,
}) => {
  return (
    <>
      <Head>
        <title>{pageTitle}</title>
        <meta name="description" content={pageDescription} />
      </Head>
      <SiteContent>
        <SkipLink>Skip to main content</SkipLink>
        <header>Page Header & Navigation</header>
        <SiteMain>
          <MainContentStart />
          <BoundedContent>{children}</BoundedContent>
        </SiteMain>
      </SiteContent>
    </>
  )
}

NextJS App Router

NextJS's App Router introduces a framework for building applications and relies on experimental React features such as React Server Components (RSCs). The App Router uses a canary version of React and includes functionality not included in the latest production version, 18.3.0.

As of SWAN 3.0, all components are marked with 'use client' - meaning they will render on the server, but also hydrate on the client.

SWAN Utility Components and CSS Classes

Because SWAN components are treated as client components, they cannot be used inside of server components (except when passed through as children props).

Instead of rendering something like <P marginTop={3}>My Paragraph</P> the CSS utility classes can be used instead: <p className="swan-mt-3">My Paragraph</p>. This approach lacks type safety, so is best avoided, if possible

Getting Started With CRA or Parcel

We will use React helmet to manage everything on the client side itself.

SwanConfigurationapp.tsxindex.tsx

import {
  getRootClassNames,
  SwanHead,
  SwanProvider,
  SWAN_BASE_URL_MAP,
  SWAN_STYLE_KEY_MAP,
  useBrowserClasses,
} from '@vp/swan'
import * as React from 'react'
import { Helmet } from 'react-helmet-async'

const eagerlyLoadedStyles = [
  SWAN_STYLE_KEY_MAP.thumbnailsHero,
  SWAN_STYLE_KEY_MAP.button,
  SWAN_STYLE_KEY_MAP.accordion,
]

export const SwanConfiguration: React.FC<unknown> = ({ children }) => {
  const browser = useBrowserClasses()
  const rootClassName = getRootClassNames()
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementation will differ
  return (
    <SwanProvider swanTenant={tenant} swanLocale={locale}>
      <Helmet
        htmlAttributes={{ class: browser }}
        bodyAttributes={{ class: rootClassName }}
      />
      <SwanHead
        renderStyleContentAsChildren
        renderWith={Helmet}
        styleSheetKeys={eagerlyLoadedStyles}
      />
      {/* Optionally, if you need, wrap ScreenProvider at this level */}
      {children}
    </SwanProvider>
  )
}

import {
  getRootClassNames,
  SwanHead,
  SwanProvider,
  SWAN_BASE_URL_MAP,
  SWAN_STYLE_KEY_MAP,
  useBrowserClasses,
} from '@vp/swan'
import * as React from 'react'
import { Helmet } from 'react-helmet-async'

const eagerlyLoadedStyles = [
  SWAN_STYLE_KEY_MAP.thumbnailsHero,
  SWAN_STYLE_KEY_MAP.button,
  SWAN_STYLE_KEY_MAP.accordion,
]

export const SwanConfiguration: React.FC<unknown> = ({ children }) => {
  const browser = useBrowserClasses()
  const rootClassName = getRootClassNames()
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementation will differ
  return (
    <SwanProvider swanTenant={tenant} swanLocale={locale}>
      <Helmet
        htmlAttributes={{ class: browser }}
        bodyAttributes={{ class: rootClassName }}
      />
      <SwanHead
        renderStyleContentAsChildren
        renderWith={Helmet}
        styleSheetKeys={eagerlyLoadedStyles}
      />
      {/* Optionally, if you need, wrap ScreenProvider at this level */}
      {children}
    </SwanProvider>
  )
}

import {
  SkipLink,
  SiteMain,
  SiteContent,
  MainContentStart,
  BoundedContent,
} from '@vp/swan'
import * as React from 'react'

export const App: React.FC<unknown> = () => {
  return (
    <SiteContent>
      <SkipLink>Skip to main content</SkipLink>
      <header>Page Header and Navigation</header>
      <SiteMain>
        <MainContentStart />
        <BoundedContent>Your Site Content</BoundedContent>
      </SiteMain>
      <footer>Your Site Footer</footer>
    </SiteContent>
  )
}

import {
  SkipLink,
  SiteMain,
  SiteContent,
  MainContentStart,
  BoundedContent,
} from '@vp/swan'
import * as React from 'react'

export const App: React.FC<unknown> = () => {
  return (
    <SiteContent>
      <SkipLink>Skip to main content</SkipLink>
      <header>Page Header and Navigation</header>
      <SiteMain>
        <MainContentStart />
        <BoundedContent>Your Site Content</BoundedContent>
      </SiteMain>
      <footer>Your Site Footer</footer>
    </SiteContent>
  )
}

import { render } from 'react-dom'
import { SwanConfiguration } from './components/SwanConfiguration'
import { App } from './app'

render(
  <SwanConfiguration>
    <App />
  </SwanConfiguration>,
  document.getElementById('root'),
)

import { render } from 'react-dom'
import { SwanConfiguration } from './components/SwanConfiguration'
import { App } from './app'

render(
  <SwanConfiguration>
    <App />
  </SwanConfiguration>,
  document.getElementById('root'),
)

Getting Started With CRA with webpack

This approach tries to manage head during build time of SPAs.

We need react-helmet-async, craco, and a few webpack plugins to configure CRA.
SwanConfiguration configures the SWAN provider using react-helmet-async, since CRA doesn't come with any head management toolkit.
We recommend using craco to modify the webpack plugin, and to inject meta tags, font preload links, font face configuration, favicons, and stylesheets.
App gives an overall pattern for the page, along with skip links for accessibility.
Index shows how to wrap your app with SwanConfiguration .

Why are we using Webpack plugins?

CRA is a client-side only Single Page Application, and SwanProvider could only update the head once it is downloaded and executed. Also, once the head is updated, the browser will start loading fonts, stylesheets, etc.

Webpack plugins will allow us to inject those in the head during the build phase itself. Thus, when this goes to the browser, all the assets could be loaded before the React app is initialized -- and therefore when the content renders, there will be no Flash of Unstyled Content (FOUC).

npm i @craco/craco html-webpack-tags-plugin html-webpack-inject-string-plugin  --save-dev

npm i @craco/craco html-webpack-tags-plugin html-webpack-inject-string-plugin  --save-dev

/**
 * Use this when you are loading everything
 * using the webpack
 **/
import * as React from 'react'
import { SwanProvider, useBrowserClasses, SWAN_BASE_URL_MAP } from '@vp/swan'
import { Helmet } from 'react-helmet-async'

// Not Using SwanHead, since those are added by webpack
const SwanConfiguration: React.FC<unknown> = ({ children }) => {
  useBrowserClasses(true)
  const rootClassName = getRootClassNames()
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementation will differ
  return (
    <SwanProvider swanTenant={tenant} swanLocale={locale}>
      <Helmet bodyAttributes={{ class: rootClassName }} />
      {/* Optionally, if you need, wrap ScreenProvider at this level */}
      {children}
    </SwanProvider>
  )
}

export default SwanConfiguration

/**
 * Use this when you are loading everything
 * using the webpack
 **/
import * as React from 'react'
import { SwanProvider, useBrowserClasses, SWAN_BASE_URL_MAP } from '@vp/swan'
import { Helmet } from 'react-helmet-async'

// Not Using SwanHead, since those are added by webpack
const SwanConfiguration: React.FC<unknown> = ({ children }) => {
  useBrowserClasses(true)
  const rootClassName = getRootClassNames()
  const { tenant, locale } = getTenantAndLocale() // Illustration function. Actual implementation will differ
  return (
    <SwanProvider swanTenant={tenant} swanLocale={locale}>
      <Helmet bodyAttributes={{ class: rootClassName }} />
      {/* Optionally, if you need, wrap ScreenProvider at this level */}
      {children}
    </SwanProvider>
  )
}

export default SwanConfiguration

const HtmlWebpackTagsPlugin = require('html-webpack-tags-plugin')
const HtmlWebpackInjectStringPlugin = require('html-webpack-inject-string-plugin')

const {
  getSwanFontRenderConfig,
  getSwanStylesheetUrl,
  SWAN_BASE_URL_MAP,
  SWAN_PUBLIC_ASSET_FOLDER,
  SwanFontNameEnum,
  SWAN_STYLE_KEY_LIST,
  SwanAssetFolders,
  getSwanAssetFolderName,
  // SWAN_STYLE_KEY_MAP, // if you dont want to load everything
  SwanPathTypeEnum,
} = require('@vp/swan')

// Get Required Meta Data from @vp/swan
const favIconFolder = `${
  SWAN_BASE_URL_MAP.default.cdn
}${SWAN_PUBLIC_ASSET_FOLDER}/${getSwanAssetFolderName(
  SwanAssetFolders.FAVICONS,
)}`

const [fontPreloadUrls, fontFaceConfig] = getSwanFontRenderConfig(
  [SwanFontNameEnum.Graphik],
  SwanPathTypeEnum.hashed,
  SWAN_BASE_URL_MAP.default.cdn,
)

const styleSheetsLinks = SWAN_STYLE_KEY_LIST.map(styleKey =>
  getSwanStylesheetUrl(
    styleKey,
    SwanPathTypeEnum.hashed,
    SWAN_BASE_URL_MAP.default.cdn,
  ),
).filter(Boolean)

const favIcons = [
  {
    path: `${favIconFolder}/favicon.ico`,
    attributes: { rel: 'shortcut icon' },
  },
  {
    path: `${favIconFolder}/apple-icon-152x152.png`,
    attributes: { rel: 'apple-touch-icon', sizes: '152x152' },
  },
  {
    path: `${favIconFolder}/apple-icon-120x120.png`,
    attributes: { rel: 'apple-touch-icon', sizes: '120x120' },
  },
  {
    path: `${favIconFolder}/apple-icon-76x76.png`,
    attributes: { rel: 'apple-touch-icon', sizes: '76x76' },
  },
  {
    path: `${favIconFolder}/apple-icon-60x60.png`,
    attributes: { rel: 'apple-touch-icon', sizes: '60x60' },
  },
]

// Adding StyleSheets

module.exports = {
  webpack: {
    plugins: [
      // Append link tags to head
      new HtmlWebpackTagsPlugin({
        links: [
          // Add FavIcons
          ...favIcons,
          // Add Fonts Pre Load URLs
          ...fontPreloadUrls.map(path => ({
            path,
            attributes: { rel: 'preload', as: 'font', crossorigin: true },
          })),
          // Add StyleSheets
          ...styleSheetsLinks,
        ],
        usePublicPath: false,
        append: true,
        // Add Meta Tags
        metas: [
          { attributes: { charset: 'UTF-8' } },
          {
            attributes: { 'http-equiv': 'X-UA-Compatible', content: 'IE=edge' },
          },
          {
            attributes: {
              name: 'viewport',
              content: 'width=device-width, initial-scale=1.0',
            },
          },
          { attributes: { 'format-detection': 'telephone=no' } },
        ],
      }),
      new HtmlWebpackInjectStringPlugin({
        search: '</head>',
        inject: `<style>${fontFaceConfig.replaceAll(/[\s\n]+/g, '')}</style>`,
      }),
    ],
  },
}

const HtmlWebpackTagsPlugin = require('html-webpack-tags-plugin')
const HtmlWebpackInjectStringPlugin = require('html-webpack-inject-string-plugin')

const {
  getSwanFontRenderConfig,
  getSwanStylesheetUrl,
  SWAN_BASE_URL_MAP,
  SWAN_PUBLIC_ASSET_FOLDER,
  SwanFontNameEnum,
  SWAN_STYLE_KEY_LIST,
  SwanAssetFolders,
  getSwanAssetFolderName,
  // SWAN_STYLE_KEY_MAP, // if you dont want to load everything
  SwanPathTypeEnum,
} = require('@vp/swan')

// Get Required Meta Data from @vp/swan
const favIconFolder = `${
  SWAN_BASE_URL_MAP.default.cdn
}${SWAN_PUBLIC_ASSET_FOLDER}/${getSwanAssetFolderName(
  SwanAssetFolders.FAVICONS,
)}`

const [fontPreloadUrls, fontFaceConfig] = getSwanFontRenderConfig(
  [SwanFontNameEnum.Graphik],
  SwanPathTypeEnum.hashed,
  SWAN_BASE_URL_MAP.default.cdn,
)

const styleSheetsLinks = SWAN_STYLE_KEY_LIST.map(styleKey =>
  getSwanStylesheetUrl(
    styleKey,
    SwanPathTypeEnum.hashed,
    SWAN_BASE_URL_MAP.default.cdn,
  ),
).filter(Boolean)

const favIcons = [
  {
    path: `${favIconFolder}/favicon.ico`,
    attributes: { rel: 'shortcut icon' },
  },
  {
    path: `${favIconFolder}/apple-icon-152x152.png`,
    attributes: { rel: 'apple-touch-icon', sizes: '152x152' },
  },
  {
    path: `${favIconFolder}/apple-icon-120x120.png`,
    attributes: { rel: 'apple-touch-icon', sizes: '120x120' },
  },
  {
    path: `${favIconFolder}/apple-icon-76x76.png`,
    attributes: { rel: 'apple-touch-icon', sizes: '76x76' },
  },
  {
    path: `${favIconFolder}/apple-icon-60x60.png`,
    attributes: { rel: 'apple-touch-icon', sizes: '60x60' },
  },
]

// Adding StyleSheets

module.exports = {
  webpack: {
    plugins: [
      // Append link tags to head
      new HtmlWebpackTagsPlugin({
        links: [
          // Add FavIcons
          ...favIcons,
          // Add Fonts Pre Load URLs
          ...fontPreloadUrls.map(path => ({
            path,
            attributes: { rel: 'preload', as: 'font', crossorigin: true },
          })),
          // Add StyleSheets
          ...styleSheetsLinks,
        ],
        usePublicPath: false,
        append: true,
        // Add Meta Tags
        metas: [
          { attributes: { charset: 'UTF-8' } },
          {
            attributes: { 'http-equiv': 'X-UA-Compatible', content: 'IE=edge' },
          },
          {
            attributes: {
              name: 'viewport',
              content: 'width=device-width, initial-scale=1.0',
            },
          },
          { attributes: { 'format-detection': 'telephone=no' } },
        ],
      }),
      new HtmlWebpackInjectStringPlugin({
        search: '</head>',
        inject: `<style>${fontFaceConfig.replaceAll(/[\s\n]+/g, '')}</style>`,
      }),
    ],
  },
}

import {
  SkipLink,
  SiteMain,
  SiteContent,
  MainContentStart,
  BoundedContent,
} from '@vp/swan'
import * as React from 'react'

const App: React.FC<unknown> = () => {
  return (
    <SiteContent>
      <SkipLink>Skip to main content</SkipLink>
      <header>Page Header and Navigation</header>
      <SiteMain>
        <MainContentStart />
        <BoundedContent>Your Site Content</BoundedContent>
      </SiteMain>
      <footer>Your Site Footer</footer>
    </SiteContent>
  )
}

export default App

import {
  SkipLink,
  SiteMain,
  SiteContent,
  MainContentStart,
  BoundedContent,
} from '@vp/swan'
import * as React from 'react'

const App: React.FC<unknown> = () => {
  return (
    <SiteContent>
      <SkipLink>Skip to main content</SkipLink>
      <header>Page Header and Navigation</header>
      <SiteMain>
        <MainContentStart />
        <BoundedContent>Your Site Content</BoundedContent>
      </SiteMain>
      <footer>Your Site Footer</footer>
    </SiteContent>
  )
}

export default App

import React from 'react'
import ReactDOM from 'react-dom'
import App from './App'
import SwanConiguration from './SwanConfiguration'
import './index.scss'

ReactDOM.render(
  <React.StrictMode>
    <SwanConiguration>
      <App />
    </SwanConiguration>
  </React.StrictMode>,
  document.getElementById('root'),
)

import React from 'react'
import ReactDOM from 'react-dom'
import App from './App'
import SwanConiguration from './SwanConfiguration'
import './index.scss'

ReactDOM.render(
  <React.StrictMode>
    <SwanConiguration>
      <App />
    </SwanConiguration>
  </React.StrictMode>,
  document.getElementById('root'),
)

{
  "name": "your-app",
  "scripts": {
    "build": "craco build",
    "start": "craco start",
    "test": "craco test",
    "analyzer": "cra-bundle-analyzer",
    "eject": "react-scripts eject"
  },
  "overrides": {
    "@types/react": "17.0.45",
    "@types/react-dom": "17.0.17"
  },
  "resolutions": {
    "@types/react": "17.0.45",
    "@types/react-dom": "17.0.17"
  },
}

{
  "name": "your-app",
  "scripts": {
    "build": "craco build",
    "start": "craco start",
    "test": "craco test",
    "analyzer": "cra-bundle-analyzer",
    "eject": "react-scripts eject"
  },
  "overrides": {
    "@types/react": "17.0.45",
    "@types/react-dom": "17.0.17"
  },
  "resolutions": {
    "@types/react": "17.0.45",
    "@types/react-dom": "17.0.17"
  },
}

react-helmet vs. react-helmet-async

react-helmet is a package from the NFL for managing HTML elements in the <head> of the page. It is no longer maintained and hasn't been updated in years. As a result, Gatsby and Next have introduced their own head management libraries.

If you are not using one of those frameworks and are still relying on react-helmet, you may see an error like Warning: Using UNSAFE_componentWillMount in strict mode is not recommended and may indicate bugs in your code, especially in React 18. In that case, switch to react-helmet-async, which has the same API, but better supports modern version of React.

SwanProvider

Props summary:

swanTenant: Takes a valid tenant
swanLocale: Takes a valid locale
swanBaseUrl: This takes a baseUrl for the SWAN assets. Use this if you don't have swanTenant and swanLocale. If provided alongside the mentioned ones, this will have a higher priority. This falls back to our CDN. You could pass options via our Map like SWAN_BASE_URL_MAP.vistaprint.com for the .com domain.
pathType has two possible values: hashed | versioned exported via an enum SwanPathTypeEnum. Each asset is stored at two paths: one using the content hash, and one using the package version. It defaults to hashed, which is the recommended value. Not all the asset files change between different versions of SWAN, and so if they have the same content, they will also have the same hash across different versions of SWAN.
globalLinkComponent: Specify which component should it use when using the SwanLink component. Frameworks like gatsby and nextjs comes with their own link component and for CRA you might use link component from the routing library you are using.

What is swanBaseUrl?

To set the stage for this section, we'll start with a quick refresher on how the browser handles <link>/<script> tags. Feel free to skip the next paragraph if you're already familiar with optimizing load times by using same-domain requests!

Once your page's HTML is downloaded, the browser is going to discover a bunch of <link> and <script> tags that reference remote assets that need to be downloaded. If those secondary assets are served from a different domain than your HTML, then the browser will need to go through an additional connection process for each new domain. However, if those assets are served from the same domain as your HTML, then the browser can use its existing connection which saves time!

By default, SWAN will return URLs with the https://swan.prod.merch.vpsvc.com domain, but we've also made sure that our assets are available via each of our production domains (e.g. vistaprint.ie) on a proxy path /swan/. So, when building for production, we recommend that you specify the appropriate domain via the domain option in SwanProvider’s swanBaseUrl prop.

e.g. if you're building a page that will be accessed via vistaprint.es, you should specify swanBaseUrl={SWAN_BASE_URL_MAP.vistaprint.es}.

Note: Use this if you don't have swanTenant and swanLocale. SwanProvider can internally determine teh base URL if swanTenant and swanLocale are provided and fall backs to CDN. If swanBaseUrl is provided alognside these, it will have highe rpriority

Global Link Component

It is common in single-page apps to use a routing library like React Router in order to handle client-side routing. Frameworks like Gatsby and Next make use of a routing library as well.

One thing that routing libraries have in common is that they ship their own Link components that you must use throughout your SPA rather than simply rendering <a> tags. This allows the routing library to circumvent the browser's normal anchor logic and enables the library to handle the linking (and even pre-fetching in some cases).

All SWAN components are configurable in such a way that you can easily tell them to render a custom component rather than the default tag that they usually render.

Swan, Gatsby, and React-Router all export a component with the name Link which is confusing. From here on, I'll refer to those as SwanLink, GatsbyLink, and ReactRouterLink for clarity.

e.g. you can tell a SwanLink to render a GatsbyLink rather than an <a> like this:

import { Link } from '@vp/swan'
import { Link as GatsbyLink } from 'gatsby'

function MyComponent() {
  return (
    <Link as={GatsbyLink} href="#">
      Navigate somewhere
    </Link>
  )
}

import { Link } from '@vp/swan'
import { Link as GatsbyLink } from 'gatsby'

function MyComponent() {
  return (
    <Link as={GatsbyLink} href="#">
      Navigate somewhere
    </Link>
  )
}

But what if you want all SwanLink to use GatsbyLink by default? It would be tedious and error-prone to add the component prop to every instance of SwanLink.

That's where globalLinkComponent comes in.

import { SwanProvider, Link } from '@vp/swan'
import { Link as GatsbyLink } from 'gatsby'

function TopLevelConfiguration() {
  return (
    <SwanProvider globalLinkComponent={GatsbyLink}>
      <SwanSSRProvider>
        <App />
        <SomeComponent />
      </SwanSSRProvider>
    </SwanProvider>
  )
}

function SomeComponent() {
  return <Link to="/some_url">Some URL rendered via Gatsby Link</Link>
}

import { SwanProvider, Link } from '@vp/swan'
import { Link as GatsbyLink } from 'gatsby'

function TopLevelConfiguration() {
  return (
    <SwanProvider globalLinkComponent={GatsbyLink}>
      <SwanSSRProvider>
        <App />
        <SomeComponent />
      </SwanSSRProvider>
    </SwanProvider>
  )
}

function SomeComponent() {
  return <Link to="/some_url">Some URL rendered via Gatsby Link</Link>
}

With globalLinkProvider configured, all SwanLinks underneath the SwanProvider will render a GatsbyLink by default! And don't worry, you can still override any individual SwanLink's component via the component prop.

SwanHead

SwanHead takes below props

swanBaseUrl (Required): It is optional and tries to read from SwanProvider when used as the child. For cases where SwanHead is used outside the provider like gatsby-ssr or next.js _document.js, pass the appropriate value. The default value is the Swan CDN URL
swanPathType (Optional): Defaults to SwanProvider's value if inside else hashed.
styleSheetKeys (Required): List of all the stylesheets that it needs to load. Swan Doesn't support auto-loading of styles. So pass all the values. It defaults to loading all the CSS.
fontNames (Optional): List of all the fonts you want to load. Note: if you set this, you will need to list all the fonts you want, not just the ones you want to add to the default font. So if you want to use both Graphik and Tiempos on your page, you would need to set <SwanHead fontNames={[SwanFontNameEnum.Graphik, SwanFontNameEnum.Tiempos]} ...>

When using Helmet, pass additional props:

renderWith={Helmet} defaults to using React.Fragment. Works for gatsby and nextjs Head.
renderStyleContentAsChildren since Helmet expects the style content as children as opposed to the props dangerouslySetInnerHTML

Page Meta Tag

The SWAN library simplifies the management of essential page meta tags as part of the SwanHead component, ensuring optimal performance and functionality for your web application.

With SWAN, you no longer need to manually include and configure these meta tags individually. The library takes care of the following meta tags for you within the SwanHead component:

<>
  <meta key="charset" charSet="UTF-8" />
  <meta
    key="viewport"
    name="viewport"
    content="width=device-width, initial-scale=1.0"
  />
  <meta
    key="telephone format detection"
    name="format-detection"
    content="telephone=no"
  />
  <meta
    key={SWAN_VERSION_META_NAME}
    name={SWAN_VERSION_META_NAME}
    content={SWAN_VERSION}
  />
  <link
    rel="shortcut icon"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/favicon.ico"
  />
  <link
    rel="apple-touch-icon"
    sizes="152x152"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-152x152.png"
  />
  <link
    rel="apple-touch-icon"
    sizes="120x120"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-120x120.png"
  />
  <link
    rel="apple-touch-icon"
    sizes="76x76"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-76x76.png"
  />
  <link
    rel="apple-touch-icon"
    sizes="60x60"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-60x60.png"
  />
</>

<>
  <meta key="charset" charSet="UTF-8" />
  <meta
    key="viewport"
    name="viewport"
    content="width=device-width, initial-scale=1.0"
  />
  <meta
    key="telephone format detection"
    name="format-detection"
    content="telephone=no"
  />
  <meta
    key={SWAN_VERSION_META_NAME}
    name={SWAN_VERSION_META_NAME}
    content={SWAN_VERSION}
  />
  <link
    rel="shortcut icon"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/favicon.ico"
  />
  <link
    rel="apple-touch-icon"
    sizes="152x152"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-152x152.png"
  />
  <link
    rel="apple-touch-icon"
    sizes="120x120"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-120x120.png"
  />
  <link
    rel="apple-touch-icon"
    sizes="76x76"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-76x76.png"
  />
  <link
    rel="apple-touch-icon"
    sizes="60x60"
    href="https://www.vistaprint.com/swan/v3-assets/favicons/apple-icon-60x60.png"
  />
</>

By leveraging the SWAN library's meta tag management capabilities, you can focus on developing your application without worrying about the intricate details of meta tag setup.

getRootClassNames

Swan is built to be interoperable with other design systems to allow incremental adoption. In order to achieve this, everything related to swan must be within the swan class.

Generally the root class names are applied to the body tag if you want swan to work on the entire page. When doing incremental adoption, you should apply this to the html element under which you want swan to work.

It takes a configuration object with below attributes:

standardMode?: boolean (default: false)
darkMode?: boolean (default: false)

() => {
  const defaultClassName = getRootClassNames()
  const withDarkMode = getRootClassNames({ darkMode: true })
  return (
    <>
      <div>
        <em>Default ClassNames:</em> <code>{defaultClassName}</code>
      </div>
      <div>
        <em>withDarkMode ClassNames:</em> <code>{withDarkMode}</code>
      </div>
    </>
  )
}

() => {
  const defaultClassName = getRootClassNames()
  const withDarkMode = getRootClassNames({ darkMode: true })
  return (
    <>
      <div>
        <em>Default ClassNames:</em> <code>{defaultClassName}</code>
      </div>
      <div>
        <em>withDarkMode ClassNames:</em> <code>{withDarkMode}</code>
      </div>
    </>
  )
}

useBrowserClasses

This accepts an optional boolean parameter that will add the browser's name as a class name on the <head> tag. For instance, if you are using Firefox, you should see class swan-firefox on the <head> tag.

We account for the following browsers by analyzing the navigator.userAgent:

Safari
Firefox
IE
Edge (pre-Chromium, and Chromium-based)

() => {
  const cn = useBrowserClasses()
  return (
    <div>
      <em>Browser Class Name : </em> <code>{cn}</code>
    </div>
  )
}

() => {
  const cn = useBrowserClasses()
  return (
    <div>
      <em>Browser Class Name : </em> <code>{cn}</code>
    </div>
  )
}

Testing

waitForStyles

When testing SWAN components, especially in a browser-based testing solution like Playwright or Cypress, you may need to wait for SWAN styles to be loaded before running your test assertions. We provide a testing utility called waitForStyles that does exactly what it's called - it returns a promise that resolves when the SWAN style keys are loaded. To use, put await waitForStyles() in your test.

Jest Setup

UI testing in jest relies on jsdom, a node-based implementation of browser standards. The ModalDialog component relies on the native dialog element, which jsdom does not yet support. This might cause unit tests to fail with an error like "dialogRef.current.showModal is not a function." You can mock the HTMLDialogElement API in your jest setup file with the following:

// mock Dialog element
// https://github.com/jsdom/jsdom/issues/3294#issuecomment-1268330372
HTMLDialogElement.prototype.show = jest.fn(function mock(
  this: HTMLDialogElement,
) {
  this.open = true
})
HTMLDialogElement.prototype.showModal = jest.fn(function mock(
  this: HTMLDialogElement,
) {
  this.open = true
})
HTMLDialogElement.prototype.close = jest.fn(function mock(
  this: HTMLDialogElement,
) {
  this.open = false
})

// mock Dialog element
// https://github.com/jsdom/jsdom/issues/3294#issuecomment-1268330372
HTMLDialogElement.prototype.show = jest.fn(function mock(
  this: HTMLDialogElement,
) {
  this.open = true
})
HTMLDialogElement.prototype.showModal = jest.fn(function mock(
  this: HTMLDialogElement,
) {
  this.open = true
})
HTMLDialogElement.prototype.close = jest.fn(function mock(
  this: HTMLDialogElement,
) {
  this.open = false
})