Tailshuffle.sh

Some nice wrapping to help you use Tailwind Pro with Shuffle.dev. Released under MIT — see LICENSE.

tailwindui-crawler downloads the components and shuffle-package-maker packs up the HTML into Shuffle's custom library format. At the risk of stating the obvious, this tool requires an active Tailwind Plus subscription. In particular, it should go without saying that you are responsible for complying with the Tailwind Plus terms of service.

The manual steps are straightforward enough, I've just tied it all together with some script glue, fixes and polish, running the whole lot inside of Docker or Podman to keep your machine clean. Built on NixOS, but should work on macOS, Linux or Windows via WSL2 as long as you've Docker or Podman installed. Many thanks of course to @tailwindlabs for their years of love poured into Tailwind (go buy it!), @kiliman and @shuffle-dev for the code that does 90% of the heavy lifting here.

Usage

./tailshuffle.sh              # show help, offer to run full pipeline
./tailshuffle.sh all          # full interactive pipeline

## Or, run individual steps
./tailshuffle.sh build        # build the Docker image
./tailshuffle.sh download     # download components
./tailshuffle.sh convert      # convert to shuffle format
./tailshuffle.sh catalog      # generate components-catalog.json (LLM context)
./tailshuffle.sh package      # zip + validate
./tailshuffle.sh clean        # remove build artefacts

The final output is tailwind-shuffle-components.zip, ready to upload. Components are cached in cache/ for inspection and subsequent runs.

Once you're done, you can build using the Pro components inside of Shuffle as you please.

Manual Steps

If you already have node/npx ready to go, you can replicate most of what the pipeline does by hand:

Step 1 — Set up your credentials:

# .env.example
[email protected]
PASSWORD=your-tailwindui-password
OUTPUT=/app/output
LANGUAGES=html
COMPONENTS=all
BUILDINDEX=0
TEMPLATES=0

Step 2 — Clone and patch tailwindui-crawler:

git clone https://github.com/kiliman/tailwindui-crawler.git
cd tailwindui-crawler
patch -p1 < /path/to/fix-crawler-deps.patch
npm install

npm audit will report a couple of vulnerabilities. The patch modifies package.json to correct them. It:

1. Removes unused dependencies — cookie, form-urlencoded, and glob aren't actually used at runtime
2. Adds an npm override for tmp — forces version ^0.2.4 instead of the vulnerable ^0.0.33

The vulnerability (GHSA-52f5-9888-hmc6) is a symlink-based arbitrary file write in tmp. It comes in through a deep dependency chain:

all-contributors-cli → inquirer → external-editor → tmp@^0.0.33

external-editor pins tmp to ^0.0.33, which semver locks it to <0.1.0 — so it can never reach the patched 0.2.x line without an override.

Step 3 — Download components:

npm start

This gives you files in ./output/html/ui-blocks/{marketing,application-ui,ecommerce}/...

Step 4 — Convert with shuffle-package-maker:

npx shuffle-package-maker /path/to/tailwindui-crawler/output/html/ui-blocks --preset=tailwindui

Note that the crawler outputs to html/ui-blocks/, not html/components/ as the shuffle-package-maker docs suggest.

Step 5 — Brand the library metadata (optional):

unzip output.zip shuffle.config.json

# shuffle reads this to display the library name/description in their UI
sed -i \
  -e 's|Tailwind UI all components|[email protected]|' \
  -e 's|Tailwind UI All|Tailwind UI Pro|' \
  shuffle.config.json

# delete and re-add to avoid stored vs deflated warnings
zip -d output.zip shuffle.config.json
zip output.zip shuffle.config.json

Step 6 — Generate a component catalog for LLMs (optional, but useful):

node catalog.mjs

{
  "_meta": {
    "generated": "2026-02-05T22:08:59.571Z",
    "totalComponents": 611,
    "source": "output/components",
    "categories": {
      "application_shells": 23,
      "components": 84,
      "data_display": 19,
      "elements": 76,
      "feedback": 17,
      "forms": 74,
      "headings": 25,
      "layout": 38,
      "lists": 44,
      "navigation": 54,
      "overlays": 24,
      "sections": 133
    }
  },
  "application_shells": {
    "multi_column": [
      "constrained_three_column",
      "constrained_with_sticky_columns",
      "full_width_secondary_column_on_right",
      "full_width_three_column",
      "full_width_with_narrow_sidebar",
      "full_width_with_narrow_sidebar_and_header"
    ],
    "sidebar": [
      "brand_sidebar_with_header",
      "dark_sidebar_with_header",
      "sidebar_with_header",
      "simple_brand_sidebar",
      "simple_dark_sidebar",
      "simple_sidebar",
      "with_constrained_content_area",
      "with_off_white_background"
    ],
    "stacked": [
      "brand_nav_with_overlap",
      "branded_nav_with_compact_lighter_page_header",
      "branded_nav_with_lighter_page_header",
      "on_subtle_background",
      "two_row_navigation_with_overlap",
      "with_bottom_border",
      "with_compact_lighter_page_header",
      "with_lighter_page_header",
      "with_overlap"
    ]
  },
  "components": {
    "category_filters": [
      "sidebar_filters",
      "with_centered_text_and_dropdown_product_filters",
      "with_dropdown_product_filters",
      "with_expandable_product_filter_panel",
<snip>

Step 7 — Upload to Shuffle.dev and make pages.

Debugging

I've tested this fairly extensively, at least in Docker, though Podman should work wihout issue. That said, if you do run into anything...

• Login fails — check your subscription; escape special characters in your password (e.g. \$)
• Empty output — check cache/ for downloaded files; try DEBUG=1 in .env
• Missing components — set COMPONENTS=all and FORCE_UPDATE=1 in .env