Install in Next.js project

You can create a new Next.js project with create-next-app.

Installation

Install gluestack-style and it's peer dependencies using npm or yarn.

# using npm

npm i @gluestack-style/react react-native-web react-native-svg

# using yarn

yarn add @gluestack-style/react react-native-web react-native-svg

Setup Config

To configure gluestack-style, you will need to create a gluestack-style.config.ts file (.js works too) in the root of your project. In this config file, you can define your theme tokens, breakpoints, and any other settings that you want to use throughout your application.

For example, in gluestack-style.config.ts:

import { createConfig } from '@gluestack-style/react';

export const config = createConfig({
  aliases: {
    bg: 'backgroundColor',
    bgColor: 'backgroundColor',
    rounded: 'borderRadius',
    h: 'height',
    w: 'width',
  },
  tokens: {
    colors: {
      primary0: '#ffffff',
      primary400: '#c084fc',
      primary500: '#a855f7',
      primary600: '#9333ea',
    },
    space: {
      4: 16,
      5: 20,
      6: 24,
    },
    radii: {
      sm: 4,
      md: 6,
    },
    letterSpacings: {
      md: 0,
    },
    lineHeights: {
      sm: 20,
      md: 22,
    },
    fontWeights: {
      normal: '400',
      medium: '500',
    },
    fontSizes: {
      sm: 14,
      md: 16,
    },
    mediaQueries: {
      sm: '@media (min-width: 480px)',
      md: '@media (min-width: 768px)',
    },
  },
  globalStyle: {
    variants: {
      shadow: {
        softShadow: {
          shadowOffset: {
            width: 0,
            height: 0,
          },
          shadowRadius: 10,
          shadowOpacity: 0.1,
          _android: {
            shadowColor: '$primary500',
            elevation: 5,
            shadowOpacity: 0.05,
          },
        },
      },
    },
  },
} as const);

type ConfigType = typeof config;

declare module '@gluestack-style/react' {
  interface ICustomConfig extends ConfigType {}
}

Setup StyledProvider

You need to setup StyledProvider with config at the root of your application. Once your config file is set up, you can import it and pass it as a prop to the StyledProvider component. This will make the configuration options available to all components using the styled function.

Page router setup

If you are using page router, you can wrap your page component with StyledProvider in pages/_app.tsx or pages/_app.jsx file.

import { config } from "@/gluestack-style.config"
import "@/styles/globals.css"
import { StyledProvider } from "@gluestack-style/react"
import type { AppProps } from "next/app"

export default function App({ Component, pageProps }: AppProps) {
  return (
    <StyledProvider config={config}>
      <Component {...pageProps} />
    </StyledProvider>
  )
}

App directory setup

Next.js 13 introduces a new app/ directory / folder structure. By default it uses Server Components. However, gluestack-style only works in client-side components.

To use gluestack-style in server components, you need to convert them into client-side component by adding a 'use client'; at the top of your file.

To use gluestack-style in app directory, you can wrap StyledProvider in your own client Component. For example, in app/provider.tsx:

"use client"

import { StyledProvider } from "@gluestack-style/react"
import React from "react"
import { config } from "../../config"

const Provider = ({ children }: { children: React.ReactNode }) => {
  return <StyledProvider config={config}>{children}</StyledProvider>
}

export default Provider

You can wrap your root component with StyledProvider in app/layout.tsx.

import "./globals.css"
import Provider from "./provider"

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <Provider>{children}</Provider>
      </body>
    </html>
  )
}

Note: You need to pass config to StyledProvider otherwise aliases and design tokens will not work.

Setup next.config.js

To use gluestack-style with server-side rendering, you need to configure your project to transpile the modules correctly. The easiest way to do this is by using the withGluestackUI Next.js adapter. This adapter adds the necessary configuration to your project to ensure that your gluestack-style dependencies transpiled correctly for server-side rendering.

Install the adapter using npm or yarn:

# using npm

npm i @gluestack/ui-next-adapter

# using yarn

yarn add @gluestack/ui-next-adapter

Then, add the adapter to your next.config.js file:

/** @type {import('next').NextConfig} */

const { withGluestackUI } = require('@gluestack/ui-next-adapter');
const nextConfig = {
  reactStrictMode: true,
};

module.exports = withGluestackUI(nextConfig);

Server-side Rendering

It's also recommended to set up your server-side rendering (SSR) correctly. To do this, you will need to use the flush() function exported by the library and call it in your _document.tsx or _document.jsx file.

To prevent flickering, the gs class should be attached, which increases the specificity of any inline styles that are being used.

import * as React from "react"
import { Html, Head, Main, NextScript } from "next/document"
import { AppRegistry } from "react-native"
import { flush } from "@gluestack-style/react"

function Document() {
  return (
    <Html lang="en" className="gs">
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

export const style = `
html, body, #__next {
  width: 100%;
  /* To smooth any scrolling behavior */
  -webkit-overflow-scrolling: touch;
  margin: 0px;
  padding: 0px;
  /* Allows content to fill the viewport and go beyond the bottom */
  min-height: 100%;
}`

Document.getInitialProps = async ({ renderPage }: any) => {
  AppRegistry.registerComponent("Main", () => Main)
  const { getStyleElement } = AppRegistry.getApplication("Main")
  const page = await renderPage()

  const styles = [
    // eslint-disable-next-line react/jsx-key
    <style dangerouslySetInnerHTML={{ __html: style }} />,
    getStyleElement(),
    ...flush(),
  ]
  return { ...page, styles: React.Children.toArray(styles) }
}

export default Document

Babel Plugin (Optional)

You can also add the babel plugin to your project if you want to perform all style calculations during build time. The plugin can be installed via npm or yarn and should be added to your babel config.

Installation

Install it as development dependency.

# using npm

npm i --save-dev @gluestack-style/babel-plugin-styled-resolver

# using yarn

yarn add --dev @gluestack-style/babel-plugin-styled-resolver

Usage

Add it to babel.config.js or .babelrc.

// babel.config.js
module.exports = {
  plugins: ["@gluestack-style/babel-plugin-styled-resolver"],
}

// .babelrc
{
  "plugins": ["@gluestack-style/babel-plugin-styled-resolver"]
}

That's it 🎉

You are ready to use gluestack-style!

import React from "react"
import { styled } from "@gluestack-style/react"
import { View } from "react-native"

const Box = styled(View, {
  bg: "$primary500",
  h: "$6",
  w: "$6",
})

const App = () => {
  return <Box />
}

export default App