Skip to Content
🎉 Coral now has an MCP Server, check out the docs
DocumentationInstallation

Installation

Watch — Getting started with Coral

Github Packages access

All packages under the @octopus-energy scope require a Github PAT token to be installed.

Please add the following to your user-level .npmrc file, replacing GH_OCTOPUS_ENERGY_READ_TOKEN with the GH_OCTOPUS_ENERGY_READ_TOKEN value from 1Password 

~/.npmrc
@octopus-energy:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=GH_OCTOPUS_ENERGY_READ_TOKEN

Install dependencies

npm i @octopus-energy/coral @octopus-energy/coral-design @octopus-energy/icons @octopus-energy/utils

Install dev dependencies

npm i -D @pandacss/dev

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 "@octopus-energy/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/@octopus-energy/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: "@octopus-energy/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/@octopus-energy/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 it on a Next.js project like so:

You’re ready to go!

You can access all Coral components via subpaths of the main package:

import { Card } from "@octopus-energy/coral/atoms";
import { ActionCard } from "@octopus-energy/coral/molecules";
import { Header } from "@octopus-energy/coral/organisms";

Setting up Vercel with an NPMJS token

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

  • Go to your Vercel project homepage
  • Click “Environment Variables” in the left menu
  • Click the “Link Shared Environment Variables” tab
  • Search for “NPM_RC”
  • Select the “NPM_RC” variable from the list
  • Click “Save”

This will have linked the organisation’s NPM_RC values to your Vercel project which will get automatically used at build time. Learn more about Vercel’s project level linking .

Installation with Github Actions / Circle CI

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

Github Actions

During your dependency installation step, run a command to set the GH_OCTOPUS_ENERGY_READ_TOKEN token. This token is available to all repos inside the octopus-energy Github organisation.

testBuild:
    name: Run build script
    runs-on: ubuntu-latest
    steps:
        - name: Install dependencies with pnpm
          run: |
              pnpm config set @octopus-energy:registry https://npm.pkg.github.com/
              pnpm config set //npm.pkg.github.com/:_authToken ${{ secrets.GH_OCTOPUS_ENERGY_READ_TOKEN }}
              pnpm install

Circle CI

  • We use Circle CI Context  to distribute tokens across the organisation
  • During your dependency installation step, run a command to set the GH_OCTOPUS_ENERGY_READ_TOKEN token
workflows:
  build:
    jobs:
      - build:
          context:
            - NPM_TOKENS
jobs:
  build:
    working_directory: ~/repo
    docker:
      - image: circleci/node:14.18.1
    steps:
      - checkout
      - run:
          name: Install Dependencies with pnpm
          command: |
            pnpm config set @octopus-energy:registry https://npm.pkg.github.com/
            pnpm config set //npm.pkg.github.com/:_authToken ${GH_OCTOPUS_ENERGY_READ_TOKEN}
            pnpm install
Last updated on
Coral Configuration