Uploading UI Library

This page contains important information about preparing and uploading a user's library. Please read the documentation carefully or use the left menu to navigate to the desired section.

Jump to Tailwind UI or Flowbite uploading info.

We would appreciate your feedback: support@shuffle.dev

Uploading flow

UI library upload consists of just a few steps:

1. Package preparation - according to this documentation.
2. Upload the ZIP file with a package - using the uploader in the dashboard.
3. Wait for Shuffle to process the uploaded library.
4. Start using the library in projects.

Package structure

Common

• shuffle.config.json - configuration file in JSON format which complies with schema (view description).
• UI components set - provided as separate HTML files with links pointing to them in the config or as HTML strings directly in the config.

Framework specific

Tailwind CSS (example package)

Tailwind config - Tailwind configuration file should be provided as a link to the JSON file present in the library package (tailwindConfigFile field) or as a JSON object in the JSON configuration file (tailwindConfig field).

Bootstrap (example package)

Variables SCSS - sass variables file should be provided as a link to SASS file present in the library package (sassVariablesFile field) or as a text field in the JSON configuration file (sassVariables field).

Bulma (example package)

Variables SCSS - sass variables file should be provided as a link to the SASS file present in the library package (sassVariablesFile field) or as a text field in the JSON configuration file (sassVariables field).

Configuration file - shuffle.config.json

Go to the detailed and technical schema description

Required fields

• name - the library name
• description - short description
• framework - one of 3 options available - `tailwind`, `bootstrap`, `bulma`.
• categories - an array of objects with library components formatted as defined in the configuration schema.

Required fields, framework dependent

• tailwindConfig / tailwindConfigFile - for Tailwind CSS framework.
• sassVariables / sassVariablesFiles - for Bootstrap or Bulma framework.

Optional fields

• icon - icon file path
• iconDarkMode - icon file path for dark mode
• assetsConfiguration - assets configuration object

Components HTML

The contents of component files (provided in the configuration file or in the HTML component file) should contain only component HTML, without HTML/head/body tags.
Every component should be wrapped into a single HTML tag like `div` or `section`.

<div><!-- Code --></div>

Assets configuration (optional)

Define asset configuration in the main JSON configuration file. This will upload additional assets, like images used in components, with the library. Also provide paths to additional JS and CSS files that will be imported into the editor while using this custom library.

When uploading the library with assets configuration present in the configuration:

• file size limit is 1 MB per file
• assetsPath parameter should be provided (if assets exist in the package) and should point to the main assets directory (in the library package root folder)
• JS and CSS files can be defined as paths to files added in a library package, within assetsPath directory, or as links to CDN versions (see configuration schema for more information)

Library icons (optional)

Provide library icons when creating the configuration.

Icons can be defined for light and dark mode separately in JSON configuration fields:

• icon
• iconDarkMode

If defined, each field should contain a path to the existing file in the user library package. The file size limit is 200 KB per icon file. Allowed extensions are jpeg, png, gif, and svg.

Config schema documentation

The configuration file included in the package should be consistent with the defined JSON schema.

To ensure that the configuration file is correct, add the following line at the beginning of the JSON file:

{
    "$schema": "https://shuffle.dev/user-library/schema.json",
}

This will allow you to validate the configuration file using the JSON schema validator built into your favorite code editor.

Go to the detailed and technical schema description.

Containers (buckets)

Buckets are "droppable" spaces in components. Later, after library import into Shuffle, it will be possible to drop components into this element. Containers - HTML elements - should be marked with a custom dataset attribute - "data-bucket" with a numeric value starting from 1. Each "data-bucket" should have a unique value within the component.

Good examples are vertical navigation components in dashboard libraries in Shuffle. Buckets are often used there, allowing users to add other components on the right side of vertical navigation.

Example code:

<div class="mx-auto xl:ml-xss xl:pl-4" data-bucket="1"></div>

How to prepare a library package?

The ZIP file should contain:

• Library configuration JSON file - go to detailed/technical schema description,
• Tailwind config file or SCSS variables file (can also be provided in the library configuration file) - depending on the chosen framework,
• Components as HTML files (can also be provided in the library configuration file),
• Additional styles or JavaScript scripts (optional),
• Directory with assets files (optional).

You can automate uploading process with the Shuffle Package Maker.

We value your feedback!

Feedback is important to us and helps us improve this tool. Please take a moment to share your experience and suggestions with our Support Team.

Pricing / Disclaimers about license and future use

User Library Uploader is free of charge during beta tests (until the end of October 2024). After that time, it will be possible to revise the subscription to continue use (access to uploader and projects based on uploaded libraries). All pricing details will be available soon.