Skip to Content
🎉 Coral x Panda has been released 🎉 Read the Migration Guide
DocumentationGetting startedInstallation

Installation

Watch — Getting started with Coral

@krakentech NPMJS access

All packages under the @krakentech scope require a NPMJS token to be installed.

If you do not have one already, create an .npmrc file at the root of your project:

touch .npmrc

Be sure to ignore this .npmrc file in your .gitignore

Add the following snippet to your .npmrc file, replacing NPM_TOKEN with the “NPM_TOKEN” value from 1Password 

.npmrc
# NPMJS Kraken Tech Organisation Token
//registry.npmjs.org/:\_authToken=NPM_TOKEN

Again, this .npmrc file should only live locally to each developer, please do not version control this file.

Installing the required packages

Setting up the CoralConfigProvider

Coral requires that you have the CoralConfigProvider at the root layout or App level of your project, depending on the Next.js router paradigm in use.

To learn more about configuring the CoralThemeProvider, please see the Configuration docs.

Configure Panda CSS

To configure Panda CSS, create a panda.config.ts file in the root of your project and add the following content:

panda.config.ts
import { defineConfig } from '@pandacss/dev';
import { createCoralPreset, coralHooks, coralLayers } from '@krakentech/coral-design';
 
export default defineConfig({
    presets: [
        createCoralPreset({}),
    ],
    include: [
        // Add your project files to statically analyse here
        './src/**/*.{js,jsx,ts,tsx}',
        // You must include the Coral Design build info file to ensure that the design tokens are available in your project.
        // This file is generated by the Coral Design build process.
        './node_modules/@krakentech/coral-design/dist/panda.buildinfo.json',
    ],
    exclude: [
        // Add project files to ignore here (e.g. test files)
        './src/tests/**/*.{js,jsx,ts,tsx}',
    ],
    // The following options need to be added, but do not need to be changed
    preflight: false,
    outExtension: 'js',
    importMap: '@krakentech/coral-design',
    jsxFramework: 'react',
    hash: true,
    syntax: 'object-literal',
    strictPropertyValues: true,
    hooks: coralHooks,
    layers: coralLayers
});

The example above uses a wildcard to target everything within the src directory, but you can be more specific in your include field, where the path would depend on your file structure within Next.js (app or pages router / with or without the src directory):

You will also need to ensure that anywhere that you use Coral Design components, the files are included in the include array so that Panda CSS can statically analyse them, for example, if you have a components directory:

panda.config.ts
export default defineConfig({
    include: [
        './src/components/**/*.{js,jsx,ts,tsx}',
        './src/app/**/*.{js,jsx,ts,tsx}',
    ],
    ...
});

If you do use the wildcard approach, ensure that any directories you want to exclude are added to the exclude array, for example, if you have a tests directory:

panda.config.ts
export default defineConfig({
    ...
    exclude: [
        './src/tests/**/*.{js,jsx,ts,tsx}',
    ],
    ...
});

Using Blueprint?

You’ll need to pass in build info from Blueprint to the include array as well:

panda.config.ts
export default defineConfig({
    include: [
        "./node_modules/@krakentech/coral-design/dist/panda.buildinfo.json",
        "./node_modules/@krakentech/blueprint-utils/dist/panda.buildinfo.json",
        "./node_modules/@krakentech/blueprint-dashboard/dist/panda.buildinfo.json",
    ],
    ...
});

Configure PostCSS

To configure PostCSS you must include a postcss.config.cjs file in the root of your project to ensure that Panda CSS works correctly with PostCSS. Create a postcss.config.cjs file and add the following content:

postcss.config.cjs
module.exports = {
    plugins: {
        '@pandacss/dev/postcss': {},
    },
};

Import styles

At the root of your app, create a file named panda.css and add the following content:

@layer reset, base, tokens, recipes, coral_utilities;

Then, in your main entry file, import the styles:

Installing Chromatophore, the Octopus Energy font

Chromatophore is the official Octopus Energy font. Install on a Next.js project like so:

Coral publishes multiple packages to NPMJS, you can install them as you need them:

Setting up Vercel with an NPMJS token

To allow Vercel access to our private NPM packages, you’ll need to do the following:

  • Go to your Vercel project’s “Settings” tab
  • Click “Environment Variables” in the left menu
  • Click the “Link Shared Environment Variables” tab
  • Search for “NPM_TOKEN”
  • Select the “NPM_TOKEN” variable from the list
  • Click “Link”

This will have linked the organisation’s NPMJS token to your Vercel project.

Note: Vercel docs for Environment Variables project-level-linking .

Installation with Github Actions / Circle CI

To allow Github Actions or Circle CI access to our private NPM packages, you’ll need to do the following:

Github Actions

testBuild:
    name: Run build script
    runs-on: ubuntu-latest
    steps:
        - uses: actions/checkout@v3
          with:
              fetch-depth: 0
        - uses: actions/setup-node@v3
            with:
                node-version-file: '.nvmrc'
        - uses: pnpm/action-setup@v4
            name: Install pnpm
            id: pnpm-install
            with:
                version: 8
                run_install: false
        - name: Install dependencies with pnpm
          run: |
              npm config set '//registry.npmjs.org/:_authToken' "${{ secrets.NPM_TOKEN }}"
              pnpm i

Circle CI

  • We use Circle CI Context  to save our NPM token across our organisations
  • During your dependency installation Circle CI step, run a command to set the NPM config to the NPM_TOKEN stored in our org context
workflows:
    build:
        jobs:
            - build:
                  context:
                      - NPM_PRIVATE_REGISTRIES
jobs:
    build:
        working_directory: ~/repo
        docker:
            - image: circleci/node:14.18.1
        steps:
            - checkout
            - run:
                  name: Install Dependencies
                  command: |
                      npm config set "//registry.npmjs.org/:_authToken=$NPM_TOKEN"
                      pnpm i
Last updated on
Getting startedConfiguration