@wkovacs64/sly

Sly

Sly is a CLI tool to add components, icons, and utilities as code, not dependencies. Most docs start with installation and configuration but those are boring so lets do this backwards.

After you run a command with Sly, one or more files will appear in your codebase in a directory of your choice.

These files are yours to customize^[1] and own forever after. No dependencies^[2], no build step^[3], no configuration.

For example, if you add a React component this way, it will look just like a React component you wrote yourself, or like one you copy/pasted from the internet.

1. Provide transformer functions to customize each new component as it's added to your codebase.
2. If the component you added has its own dependencies, Sly will ask you if you want to install them and offload that work to npm.
3. You are not dealing with built/compiled/minified output code. Everything in the Sly registry is curated to be used natively.

Commands

Sly does NOT require a config file IF you provide enough information in the command, so instead of telling you what each option does, let's go through what happens if you don't include each option

As an example, we'll install eraser icon from @radix-ui/icons.

--overwrite

npx @sly-cli/sly add @radix-ui/icons eraser --directory ./icons --yes --overwrite

If you don't provide --overwrite, the installation will fail if the file already exists.

--yes

npx @sly-cli/sly add @radix-ui/icons eraser --directory ./icons --yes

If you don't provide --yes, you will be prompted to confirm the installation before a file is written.

--directory

npx @sly-cli/sly add @radix-ui/icons eraser --directory ./icons

If you don't provide --directory, Sly will look for your sly.json file and look for the directory field under @radix-ui/icons in the config. If Sly can't find that config file, you will be asked which directory you want to install the icon to and Sly will create a sly.json file for you.

component

npx @sly-cli/sly add @radix-ui/icons eraser

If you don't provide a component name like eraser, Sly will show you a list of all the icons available in @radix-ui/icons and ask you to select the ones you want.

library

npx @sly-cli/sly add @radix-ui/icons

If you don't provide @radix-ui/icons, Sly will show you a list of all the libraries you've configured and ask you to select the one you want before proceeding to show you the list of icons.

add

npx @sly-cli/sly add

If you don't provide add, you're at the root of the CLI and will get a help menu

npx @sly-cli/sly

npx @sly-cli/sly

If you don't provide @sly-cli/sly, it might be because you've installed Sly already and you can just run sly directly.

npm install --save-dev @sly-cli/sly

npx sly

global installation

If you don't want to use npx, install Sly globally and you can run sly directly.

npm install -g @sly-cli/sly

sly

Configuration

If you don't pass a --directory flag to Sly, it will walk you though creating a sly.json configuration file. Here's what it looks like

{
  "$schema": "https://sly-cli.fly.dev/registry/config.json",
  "libraries": [
    {
      "name": "@radix-ui/icons",
      "directory": "./other/svg-icons",
      "postinstall": ["npm", "run", "build:icons"],
      "transformers": ["transform-icon.ts"]
    }
  ]
}

You can configure each library individually, either via the CLI or by editing the config file directly.

field	description
name	The name of the library in Sly's registry.
directory	The directory where you want to insert the components. If a component with the same name already exists, adding will fail unless you pass the --overwrite flag.
transformers	An array of paths to transformers. These paths are resolved relative to the config file, so simply listing a filename will search in the same directory as the config file.
postinstall	This is a command that will be executed each time that components are added. If multiple components are added at once, it runs once at the end.

Sly will create the sly.json in your project root by default, but you are free to move it to one of several locations.

• sly.json
• sly/sly.json
• config/sly.json
• config/sly/sly.json
• .config/sly.json
• .config/sly/sly.json
• others/sly.json
• others/sly/sly.json

Transformers

Transformers automate the initial customization steps you would normally do by hand when adding new code to your project.

When you add a component, Sly will pass it through each transformer in order, like a pipeline. For example, you could use this to format the code with Prettier, to append license information, to remove attributes from SVGs, to enforce opinionated formatting preferences, to replace imports, etc.

A transformer to convert a shadcn/ui component to match your project's style might look like this

import prettier from 'prettier'

const usesServerComponents = false
const cnFunctionDir = 'tailwind.config.ts'

/**
 * @type {import('@sly-cli/sly/dist').Transformer}
 */
export default async function transformShadcn(input, meta) {
	if (!usesServerComponents) {
		input = input.replace(/"use client".*/g, '\n')
	}

	input = input.replace('@/lib/utils', cnFunctionDir)

	input = prettier.format(input, {
		parser: 'typescript',
	})

	return input
}

Each transformer must default export a function whose first arg accepts a string, and that returns a string. Returning a promise that resolves to a string is ok too – you're allowed to use async/await here.

The second arg is meta and contains the name of the library, the source url for the component, and its license information. Some licenses require you to keep attribution, and you can add such information as a header comment in this way.

Environment variables

The --directory, --yes, and --overwrite flags can also be set as environment variables. Values set as flags will override values set as environment variables, and a directory set either way will override the sly.json config file.

DIRECTORY=./other/svg-icons YES=true OVERWRITE=true npx sly add

Custom registry

You may want a custom registry to share proprietary components with your team, or to To connect to a custom registry, use the REGISTRY_URL environment variable.

REGISTRY_URL=http://localhost:3000 npx sly

Future

• Support more libraries. Any open source library of icons, components, hooks, utilities, etc. can be added to Sly.
• Caching. We should cache the registry so we don't hit the upstream sources so often.
• Typescript config instead of JSON Is this possible? It's easy enough to read a typescript config file from the CLI, but writing new config values seemed prohibitively difficult.
• Additional registries. Right now you can point to a locally hosted registry if you wanted full control of the available libraries. If someone wanted to add their own libs while also having access to the official registry, they would need their custom registry to proxy requests to the official registry. Is that ok? Should we support multiple registries up front?
• Improved contribution flow. We should have some contribution guidelines, list of contributors.
• Convert website to ESM. The website is currently all CJS and should be ported to ESM.