Getting started

Setting Up Spor in Your Project

Spor makes building sophisticated React interfaces quick, easy, and (most importantly) fun. This guide will help you get started, whether you're using vanilla React, Next.js, or Remix.

Note: This guide assumes you're using TypeScript. If you're using plain JavaScript, just remove TypeScript-specific syntax and file extensions.

Installation

First things first—let’s install Spor and its dependencies from npm:

# pnpm
pnpm install @vygruppen/spor-react

# npm
npm install @vygruppen/spor-react

# yarn
yarn add @vygruppen/spor-react

Setting Up SporProvider

Once installed, wrap your app in the SporProvider component. This ensures all Spor components work correctly.

"Vanilla" React Setup

Find your app's entry file (e.g., src/index.tsx if using Create React App). Wrap your app in SporProvider like this:

import { createRoot } from "react-dom";
import { SporProvider } from "@vygruppen/spor-react";
import App from "./App";

const root = createRoot(document.getElementById("app"));
root.render(
  <SporProvider>
    <App />
  </SporProvider>
);

Next.js Setup

Next.js is for server-side rendering (SSR) and static site generation. To use Spor, create (or update) pages/_app.tsx and wrap your app inside SporProvider:

import type { AppProps } from "next/app";
import { SporProvider } from "@vygruppen/spor-react";
import { system } from "./theme"

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <SporProvider>
      <Component {...pageProps} />
    </SporProvider>
  );
}

export default MyApp;

Remix Setup

Remix renders React apps server-side using web standards. This very site is built with Remix!

However, CSS-in-JS libraries require a bit more setup in Remix. Follow Chakra’s guide on Remix setup⁠Ekstern lenke, but replace ChakraProvider with SporProvider. You can also check Spor’s Github repository⁠Ekstern lenke on how we have set it up on this very website.

import {
  Links,
  Meta,
  Outlet,
  Scripts,
} from "@remix-run/react";
import { SporProvider } from "@vygruppen/spor-react";

export default function App() {
  return (
    <html>
      <head>
        <link
          rel="icon"
          href="data:image/x-icon;base64,AA"
        />
        <Meta />
        <Links />
      </head>
      <body>
        <SporProvider>
          <Outlet />
        </SporProvider>
        <Scripts />
      </body>
    </html>
  );
}

Type support

Installing @vygruppen/spor-react triggers a postinstall script that generates types for your project based on the default theme. However, when using pnpm as your package manager, you may encounter an issue where the package is retrieved from the pnpm cache without the generated types.

Add the following to your package.json to ensure the typegen postinstall script is run on every install.

"scripts": {
  ...
  "postinstall": "pnpm rebuild @vygruppen/spor-react"
}

You might also get a warning after installing packages.

Ignored build scripts: @vygruppen/spor-react.                        

Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.

You then have to give the @vygruppen/spor-react package permission to run the scripts with pnpm approve-build

Themes

The themes decide what color aliases are used for the different semantic color tokens. Read about design tokens in the guide on Design Tokens⁠Ekstern lenke to learn what they are and how they are set up.

There are three premade themes available.

VyDigital (default)
CargoNet
VyTeknologi

To see what color aliases the different themes use, visit the page for Design Tokens⁠Ekstern lenke and switch between the different themes at the top.

Setting the correct theme ensures brand alignment and a consistent user experience. By default SporProvider sets VyDigital as the theme. To use CargoNet or VyUtvikling, simply import it from Spor and pass it to the SporProvider.

import { createRoot } from "react-dom";
import { SporProvider, themes } from "@vygruppen/spor-react";
import App from "./App";
import { system } from "./theme"

const root = createRoot(document.getElementById("app"));
root.render(
  <SporProvider theme={themes.CargoNet}>
    <App />
  </SporProvider>
);

Customize the theme

If you want to further customize the theme, you can both add additional tokens of your choice, and/or override existing tokens in a predefined theme.

It is possible to override all tokens, including colors, spacing, font, fontWeight, lineHeights, animations etc. The example below shows how to override tokens, and add custom ones.

import { themes, createSystem, defineConfig } from "@vygruppen/spor-react";

const customTheme = defineConfig({
    theme: {
        // color tokens
        semanticTokens: {
            colors: {
                bg: {
                    //Override the default background color of the theme
                    DEFAULT: {
                        value: {
                            _light: '#FFB7A8',
                            _dark: '#8C695D',
                        },
                    },
                },
                //Create a custom token
                custom: {
                    DEFAULT: {
                        value: {
                            _light: '#FFB7A8',
                            _dark: '#8C695D',
                        },
                    },
                },
            },
        },
        // All other tokens
        tokens: {
            spacing: {
                1: { value: '4' },
            },
            borders: {...},
            animations: {...},
            lineHeights: {...},
            fontWeights: {...},
        },
    },
})
export const system = createSystem(themes.VyDigital._config, customTheme);

You can also customize the appearance of any component by overriding its recipe (or slot recipe) directly in your theme configuration, which you must pass to the SporProvider as explained above. Please see the documentation on Customising Component Styles⁠Ekstern lenke.

Types for custom theme

To enable full TypeScript support for your custom theme values, you’ll need to perform some additional configuration steps for your application.

Configure Your Theme File:
Set up your theme as shown below in a file, such as src/theme.ts.
Install and Run the Chakra CLI:
Use the Chakra CLI to update your package's type definitions with the new theme values.

pnpm i --save-dev @chakra-ui/cli

chakra typegen src/theme.ts

To avoid running this every time you reinstall your node_modules, add a postinstall-script to your package.json

"scripts": {
  ...
  "postinstall": "chakra typegen src/theme.ts"
}

Handling Languages

Some Spor components come with small built-in texts like "show," "hide," or "next." If your app supports multiple languages, you can pass the correct language to SporProvider using the language prop:

import { SporProvider, Language } from "@vygruppen/spor-react";

<SporProvider language={Language.English}>
  ...
</SporProvider>

Supported Languages:

Norwegian (Bokmål) [default]
Norwegian (Nynorsk)
Swedish
English

If no language is specified, Norwegian Bokmål is used by default.

Next: Start using Spor Components

Once you've completed the steps above, you're all set to start using Spor. Start with learning best practices on how to use Spor components.

Learn about Spor Components

Fundamentals