SVGL Documentation

SVGL has a growing ecosystem of community-created extensions that utilize the SVGL API. These extensions allow you to integrate SVG logos into various development environments and tools, including:

• Frameworks: React, Vue, and Svelte NPM packages.
• Design Tools: Figma plugin.
• IDEs & Editors: VSCode extension, Cursor/AI extensions (Magic), and Raycast.
• CLI & Shell: SVGL CLI, PowerShell extension, and Flow Launcher.
• Other: Framer plugin, PowerToys, and SVGL Badges.

The SVGL project is built using the following technologies:

• Frontend: SvelteKit, Svelte 5, Tailwind CSS, bits-ui, and svelte-sonner.
• Styling Utilities: clsx and tailwind-merge (shadcn/ui inspired).
• Language: TypeScript.
• Content Management: Content-Collections and Shiki (syntax highlighting).
• Backend: Express with Redis.
• Tooling: Prettier with prettier-plugin-tailwindcss and Lucide Icons.

To run the API server for local development, follow these steps:

1. Generate SVG data: Navigate to the api-routes folder and run the build script.
2. Configure Environment: Create a .env file inside the api-routes folder with the following variables:
   • CORS_ORIGIN: Your local development URL (e.g., http://localhost:5173).
   • REDIS_URL: Your Redis connection string (e.g., rediss://:password@hostname:port).
3. Start the server: Run the development command.

For all available endpoints, refer to the official API documentation.

Use the following commands to initialize the MCP server for your specific environment:

• Claude Code: pnpm dlx shadcn@latest mcp init --client claude (then restart Claude Code).
• Cursor: pnpm dlx shadcn@latest mcp init --client cursor (then enable the MCP server in Cursor Settings).
• VSCode: pnpm dlx shadcn@latest mcp init --client vscode (then click 'Start' next to the shadcn server in .vscode/mcp.json).

The shadcn MCP (Model Context Protocol) server allows you to browse, search, and add React SVGs from the SVGL registry via AI coding agents.

Prerequisite: You must have the @svgl registry configured in your components.json file.

To add a logo to the svgl library, follow these steps:

1. Prepare the SVG: Optimize your SVG for the web (e.g., using SVGOMG).
   • Important: Do NOT remove the viewBox.
   • Limit: The file size must be under 21kb.
2. Upload the file: Place your .svg file in the static/library folder.
3. Register the logo: Add the logo metadata to src/data/svgs.ts using one of the supported object structures (see schema below).

The SVGL API is a free RESTful API that does not require authentication. Use the following base URLs for your requests:

• SVGs Endpoint: https://api.svgl.app
• Categories Endpoint: https://api.svgl.app/categories

Note on Rate Limiting: To avoid hitting rate limits, it is recommended to cache API responses on your side (e.g., for a few minutes) instead of requesting the same data on every call.

To contribute to svgl, fork the repository, clone it, and install dependencies using pnpm.

Prerequisites:

• Node.js 20+
• Git
• pnpm (install globally via npm install -g pnpm if not present)

Steps:

1. Clone your fork:

   git clone git@github.com:your_username/svgl.git

2. Install dependencies:

   pnpm install

git clone git@github.com:your_username/svgl.git

# Install pnpm globally if you don't have it:
npm install -g pnpm

# and install dependencies:
pnpm install

To use the shadcn/ui CLI to install SVGs directly as .tsx components, you must add the SVGL registry to your components.json file. This is an optional step if you have already configured shadcn/ui in your project.

{
  "registries": {
    "@svgl": "https://svgl.app/r/{name}.json"
  }
}

The following environment variables are required in the api-routes/.env file to run the API locally: