Installation

To get started with gluestack-ui, check out this quick installation guide. It provides simple steps to help you install and use the library in your projects.

Automatic

Manual

Automatic

Using Template

Coming soon

Manual

If you wish to install @darden/design-system into your existing project, you can proceed with the following steps:

Step 1: Install / Alias dependencies

Install

First, install the dependencies of gluestack-ui in your project. This can be done using the following command:

yarn add @darden/design-system

npm i @darden/design-system

Alias (Optional)

You can alias your local design system dependency like below.

babel.config.js

const path = require("path")
module.exports = function (api) {
  api.cache(true)
  return {
    presets: [["babel-preset-expo"]],
    plugins: [
      [
        "module-resolver",
        {
          alias: {
            "@darden/design-system": path.resolve(
              __dirname,
              "../../packages/components/src"
            ),
          },
        },
      ],
    ],
  }
}

Step 2: Server-side rendering (SSR)

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 @darden/design-system.

Next.js App Routers (which supports React Server Components)

For Next.js App Routers we will create a new registry.tsx file in the root of your project and use the flush function from @darden/design-system:

"use client"

import React, { useRef, useState } from "react"
import { useServerInsertedHTML } from "next/navigation"
import { StyleRegistry, createStyleRegistry } from "styled-jsx"
import { Html, Head, Main, NextScript } from "next/document"
// @ts-ignore
import { AppRegistry } from "react-native-web"
import { flush } from "@darden/design-system"

export default function StyledJsxRegistry({
  children,
}: {
  children: React.ReactNode
}) {
  // Only create stylesheet once with lazy initial state
  // x-ref: https://reactjs.org/docs/hooks-reference.html#lazy-initial-state
  const [jsxStyleRegistry] = useState(() => createStyleRegistry())
  const isServerInserted = useRef(false)

  useServerInsertedHTML(() => {
    AppRegistry.registerComponent("Main", () => Main)
    const { getStyleElement } = AppRegistry.getApplication("Main")
    if (!isServerInserted.current) {
      isServerInserted.current = true
      const styles = [getStyleElement(), jsxStyleRegistry.styles(), ...flush()]
      jsxStyleRegistry.flush()
      return <>{styles}</>
    }
  })

  return <StyleRegistry registry={jsxStyleRegistry}>{children}</StyleRegistry>
}

We also need to add className="gs" to the <html> element in the layout.tsx file
We also need to wrap children with StyledJsxRegistry in the layout.tsx file

The code in layout.tsx file at this point of time will look like this:

import "./globals.css"
import { Inter } from "next/font/google"
import StyledJsxRegistry from "./registry"

const inter = Inter({ subsets: ["latin"] })

export const metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
}

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

Next.js Page Routers

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

Add this code in your _document.tsx file.

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

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

Document.getInitialProps = async ({ renderPage }: any) => {
  AppRegistry.registerComponent("Main", () => Main)
  const { getStyleElement } = AppRegistry.getApplication("Main")
  const page = await renderPage()
  const styles = [getStyleElement(), ...flush()]
  return { ...page, styles: React.Children.toArray(styles) }
}

export default Document

Step 3: Setup @gluestack/ui-next-adapter

To use gluestack-ui components 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-ui components are transpiled correctly for server-side rendering.

Make the following changes in next.config.js

/** @type {import('next').NextConfig} */
const { withGluestackUI } = require("@gluestack/ui-next-adapter")

const nextConfig = {
  reactStrictMode: true,
  transpilePackages: ["@darden/design-system"],
}

module.exports = withGluestackUI(nextConfig)

Step 4: Setup provider

GluestackUIProvider is a component that makes the aliases and tokens available throughout your app. It uses React's Context API.

Next.js App Routers (which supports React Server Components)

For Next.js App Routers we will create a new providers.tsx file in the app folder which will return a client component. Now, add the following code:

// app/providers.tsx
"use client"

import { GluestackUIProvider } from "@darden/design-system"

export function Providers({ children }: { children: React.ReactNode }) {
  return <GluestackUIProvider>{children}</GluestackUIProvider>
}

This component returns a GluestackUIProvider component which wraps the children.

After creating providers.tsx file, we need to wrap the exported GluestackUIProvider component around the children in layout.tsx file. The code in layout.tsx file at this point of time will look like this:

import "./globals.css"
import { Inter } from "next/font/google"
import { Providers } from "./providers"
import StyledJsxRegistry from "./registry"

const inter = Inter({ subsets: ["latin"] })

export const metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en" className="gs gs-light">
      <body className={inter.className}>
        <Providers>
          <StyledJsxRegistry>{children}</StyledJsxRegistry>
        </Providers>
      </body>
    </html>
  )
}

Next.js Page Routers

For Next.js Page Router just add GluestackUIProvider to the root of your app and update _app.tsx as follows:

import "@/styles/globals.css"
import type { AppProps } from "next/app"
import { GluestackUIProvider } from "@darden/design-system"

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

This ensures that all components are wrapped with <GluestackUIProvider />.

Edit this page on GitHub