Create a Site

In this guide you will learn how to generate and serve a Mosaic site.

Prerequisites

To begin setting up a Mosaic site, you need to have the following software installed:

  1. Yarn v4.10.3 or higher
  2. Node.js v24 or higher

Step 1: Set Up a Mosaic Site

Export the site package from this repository into your project. It is a standard Next.js App Router app that loads the packages created by this repo, with an additional mosaic.config.mjs file to configure sources and other settings. Yarn's pack command converts the template's workspace: dependencies to published version ranges, so the exported site can install outside the monorepo.

Steps:

  1. Export and install the template:

    git clone https://github.com/jpmorganchase/mosaic.git
    cd mosaic
    yarn install --immutable
    yarn workspace @jpmorganchase/mosaic-site pack --out ../../mosaic-site.tgz
    mkdir ../mosaic-sample-site
    tar -xzf mosaic-site.tgz -C ../mosaic-sample-site --strip-components=1
    cd ../mosaic-sample-site
    yarn config set nodeLinker node-modules
    yarn install
    
  2. Configure the contents of the exported site as needed.

    • Update mosaic.config.mjs to specify your content sources and other options. Replace the reference paths to this monorepo's documentation folders with paths to your own content.
    • A local source is used to serve pages from the local file-system, which can be a clone of a remote repo.
    • A remote source is used to pull content from a remote Git repository.

Note: App Router layout. The site uses Next.js App Router (src/app/), not the legacy Pages Router (src/pages/). Key files you'll touch when customising:

  • src/app/layout.tsx — root layout, global CSS and fonts.
  • src/app/providers.tsx — client-side provider stack (optional authentication, theme, store, layout).
  • src/app/[namespace]/[...route]/page.tsx — the catch-all RSC route that loads content with the @jpmorganchase/mosaic-site-middleware loaders and renders MDX.
  • src/app/[namespace]/[...route]/MdxComponents.ts — registry for MDX-visible components (replaces the old _app.tsx component merge).
  • src/auth.ts — Auth.js v5 wiring (handlers, auth, signIn, signOut).

With auth enabled, providers.tsx mounts <SessionProvider> and <NextAuthAdapter> without a server-resolved session. The browser fetches the session after the page loads. With auth disabled, neither auth provider is mounted and no session request is made. Keep that pattern when you copy the directory; the site's README.md lists the other patterns to preserve.

Upgrading a site built on the Pages Router? See Migrate to the App Router.

sources: [
{
    disabled: process.env.NODE_ENV !== 'development',
    modulePath: '@jpmorganchase/mosaic-source-local-folder',
    namespace: 'local', // each site has its own namespace, think of this as your content's uid
    options: {
      rootDir: '../../docs', // relative path to content, which can be a clone of another repo
      prefixDir: 'local', // root path used for namespace
      extensions: ['.mdx'] // extensions of content which should be pulled
    }
 },
 {
   modulePath: '@jpmorganchase/mosaic-source-git-repo',
   namespace: 'remote', // each site has its own namespace, think of this as your content's uid
   options: {
     // To run a local instance that accesses remote repos, enter your credentials to access the BitBucket/GitHub repo
     // !! Polite Reminder... do not store credentials in code !!
     // For final deployments, you could put repo access credentials securely in environment variables provided by Gaia console.
     // credentials: "{process.env.FID}:{process.env.FID_PERSONAL_ACCESS_TOKEN}",
     // If running locally
     // create an environment variable like MOSAIC_DOCS_CLONE_CREDENTIALS to let the user define it via the CLI
     // export MOSAIC_DOCS_CLONE_CREDENTIALS="<sid>:<Personal Access Token (PAT) provided by your Repo OR password>",
     credentials: process.env.MOSAIC_DOCS_CLONE_CREDENTIALS,
     prefixDir: 'remote', // root path used for namespace
     subfolder: 'docs', // subfolder within your branch containing the docs, typically 'docs'
     repo: 'github.com/jpmorganchase/mosaic.git', // repo url without any protocol
     branch: 'main', // branch where docs are pulled from
     extensions: ['.mdx'], // extensions of content which should be pulled
     remote: 'origin' // what is the shorthand name of the remote repo, typically 'origin'
   }
 }
]

Next, navigate to your new site directory:

cd my-sample-site

Step 2: Serve the site

The example site you have generated comes preconfigured with two sources: a remote repository and a local docs folder. Sources are used by Mosaic to pull content from disparate locations and merge them into a single virtual filesystem that can be used by a Mosaic site.

Set up Git credentials

If you want the site to read from remote repositories, you need to set up an environment variable to store your Git credentials. Follow these steps:

  1. Open a terminal or command prompt.

  2. Replace <repo_username> and <personal_access_token> in the following commands with your actual Git username and personal access token.

On Unix:

export MOSAIC_DOCS_CLONE_CREDENTIALS="<repo_username>:<personal_access_token>"

On Windows:

set MOSAIC_DOCS_CLONE_CREDENTIALS="<repo_username>:<personal_access_token>"

This sets the MOSAIC_DOCS_CLONE_CREDENTIALS environment variable with your Git credentials.

Serve command

Now you can serve your Mosaic site by running the following command:

yarn serve

Access your Mosaic site from a browser using the following URLs:

That's it! Your Mosaic site is now up and running.

Next Steps:

  1. Deploy your Mosaic site to AWS or Vercel for production use.
  2. Create more pages to expand your site's content.
  3. Configure your own sources in the mosaic.config.mjs file to pull content from different locations.
  4. Theme your site
  5. Build a static export for hosting on any static CDN with no Node runtime.
Mosaic BETA

Coming soon