Skip to content

installation.md

Latest commit

 

History

History
366 lines (241 loc) · 8.85 KB

installation.md

File metadata and controls

366 lines (241 loc) · 8.85 KB
Raw
section Getting Started
title Installation
excerpt Twind is a small compiler that converts utility classes into CSS at runtime. The goal of this project is to unify the flexibility of CSS-in-JS with the carefully considered constraints of the [Tailwind CSS](https://tailwindcss.com) API.
next ./presets.md

Utility-first CSS without any build step right in the browser or any other environment like Node.js, deno, workers, ...

If you have used Tailwind CSS or other CSS-in-JS solutions, then most of the API should feel very familiar.

Important

The @twind/core package does not include any rules or variants. You need to install an existing preset or bring your own preset to get started.

Local / Bundler

Tip Twind provides several integrations for different frameworks and environments.

  1. :::cols-12{.gap-4}

    ::col-span-4 Install twind

    Twind is available on npm.

    ::col-span-8

    npm install @twind/core

    :::

  2. :::cols-12{.gap-4}

    ::col-span-4 Define the configuration

    Using an extra file, twind.config.js, allows some tools like IntelliSense to find your configuration.

    ::col-span-8

    import { defineConfig } from '@twind/core'

export default defineConfig({
  /* options */
})

    :::

  3. :::cols-12{.gap-4}

    ::col-span-4 Load Twind in your application entry point.

    install creates and registers a twind instance that will generate the styles. This allows third-party packages to import tw from the twind package and get the same instance.

    ::col-span-8

    import { install } from '@twind/core'
import config from './twind.config'

// activate twind - must be called at least once
install(config)

    :::

  4. Optional: Install and configure the recommended presets @twind/preset-autoprefix and @twind/preset-tailwind.

    :::cols-12{.gap-4}

    ::col-span-4 Install the presets

    All presets are available on npm.

    ::col-span-8

    npm install @twind/preset-autoprefix @twind/preset-tailwind

    :::

    :::cols-12{.gap-4}

    ::col-span-4 Configure the presets

    Each preset must be added to the presets array in the configuration.

    ::col-span-8

    import { defineConfig } from '@twind/core'
import presetAutoprefix from '@twind/preset-autoprefix'
import presetTailwind from '@twind/preset-tailwind'

export default defineConfig({
  presets: [presetAutoprefix(), presetTailwind()],
})

    :::

  5. :::cols-12{.gap-4}

    ::col-span-4 Start using Twind in your HTML

    Start using Twind classes to style your content.

    ::col-span-8

    <h1 class="text-3xl font-bold underline">Hello world!</h1>

    :::

  6. Optional: Prevent FOUC

    Incase you are not using static extraction to include the generated styles on the server apply the following pattern to prevent FOUC:

    <body class="!block" style="display: none">
  <!-- ... -->
</body>

    If any element has the autofocus attribute, Twind will focus it after all styles are injected.

TODO: Whats next? List and links of framework integrations. All official integrations are available on npm with the prefix @twind/with-.

Browser Usage

Twind is available as a global browser script and can be used directly in the browser.

Tip

We recommend to use Twind CDN if you want to use Tailwind utilities.

  1. :::cols-12{.gap-4}

    ::col-span-4 Add the Twind script to your HTML

    Add the script tag to the <head> of your HTML file.

    ::col-span-8

    <head>
  <script src="https://cdn.jsdelivr.net/npm/@twind/core@1" crossorigin></script>
</head>

    :::

  2. :::cols-12{.gap-4}

    ::col-span-4 Create the environment

    install creates a twind instance that will observe class attributes and generate the corresponding styles.

    ::col-span-8

    <head>
  <script src="https://cdn.jsdelivr.net/npm/@twind/core@1" crossorigin></script>
  <script>
    twind.install({
      /* options */
    })
  </script>
</head>

    :::

  3. Optional: Install and configure the recommended presets @twind/preset-autoprefix and @twind/preset-tailwind.

    :::cols-12{.gap-4}

    ::col-span-4 Add the presets script to your HTML

    All presets are available on npm.

    ::col-span-8

    <head>
  <script
    src="https://cdn.jsdelivr.net/combine/npm/@twind/core@1,npm/@twind/preset-autoprefix@1,npm/@twind/preset-tailwind@1"
    crossorigin
  ></script>
</head>

    ::col-span-4 Configure the presets

    Each preset must be added to the presets array in the configuration.

    ::col-span-8

    <head>
  <script
    src="https://cdn.jsdelivr.net/combine/npm/@twind/core@1,npm/@twind/preset-autoprefix@1,npm/@twind/preset-tailwind@1"
    crossorigin
  ></script>
  <script>
    twind.install({
      presets: [twind.presetAutoprefix(/* options */), twind.presetTailwind(/* options */)],
    })
  </script>
</head>

    :::

  4. :::cols-12{.gap-4}

    ::col-span-4 Start using Twind in your HTML

    Start using Twind classes to style your content.

    ::col-span-8

    <body>
  <h1 class="text-3xl font-bold underline">Hello world!</h1>
</body>

    :::

Twind CDN

Twind CDN is a drop-in replacement for Tailwind CSS Play CDN that is 6 times smaller (104kb vs 17kB) without any build step right in the browser.

Hint > @twind/preset-autoprefix and @twind/preset-tailwind are included out-of-the-box.

  1. :::cols-12{.gap-4}

    ::col-span-4 Add the Twind CDN script to your HTML

    Add the script tag to the <head> of your HTML file.

    ::col-span-8

    <head>
  <script src="https://cdn.twind.style" crossorigin></script>
</head>

    :::

  2. Optional: Add additional presets — @twind/preset-autoprefix and @twind/preset-tailwind are already included in Twind CDN.

    To use other presets add their ids to the script src attribute:

    :::cols-12{.gap-4}

    ::col-span-4 Add the preset to Twind CDN script in your HTML

    All presets are available on npm.

    ::col-span-8

    <head>
  <script src="https://cdn.twind.style/ext,line-clamp,forms,typography" crossorigin></script>
</head>

    :::

    :::cols-12{.gap-4}

    ::col-span-4 Configure the presets

    Each preset must be added to the presets array in the configuration.

    ::col-span-8

    <head>
  <script src="https://cdn.twind.style/ext,line-clamp,forms,typography" crossorigin></script>
  <script>
    twind.install({
      presets: [
        twind.presetExt(/* options */)
        twind.presetLineClamp(/* options */)
        twind.presetTailwindForms(/* options */)
        twind.presetTypography(/* options */)
     ],
    })
  </script>
</head>

    :::

  3. :::cols-12{.gap-4}

    ::col-span-4 Start using Twind in your HTML

    Start using Twind classes to style your content.

    ::col-span-8

    <body>
  <h1 class="text-3xl font-bold underline">Hello world!</h1>
</body>

    :::

What to read next

Get familiar with some of the core concepts that make Twind different from writing traditional CSS.

:::cols-2{.gap-x-8.gap-y-4}

::col-span-1

Integrations

How to use Twind in different frameworks and environments.

::col-span-1

Migration

We have collected a list of changes in Migration › Twind v0.16. A detailed migration guide will follow.

:::