# tweakcn: a visual theme editor for shadcn/ui and Tailwind CSS

> tweakcn is a no-code editor that turns shadcn/ui's uniform look into something custom, exporting themes as CSS variables. It runs as a hosted app at tweakcn.com or locally as a Next.js project.

**jnsahaj/tweakcn** — A visual no-code theme editor for shadcn/ui components

- Repository: https://github.com/jnsahaj/tweakcn
- Website: https://tweakcn.com
- Stars: 10,422 · Forks: 659
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/jnsahaj-tweakcn

## The problem tweakcn targets: every shadcn/ui app looks the same

The README states the motivation plainly: sites built with shadcn/ui "famously look the same." That is a real consequence of how shadcn/ui works. Components are copied into your repository, and their appearance is driven by CSS custom properties (background, foreground, primary, radius, and so on) that ship with sensible defaults. Changing those defaults by hand means editing a variables block, guessing at contrast, and reloading to see the result.

tweakcn is aimed at the person doing that editing. The README describes it as a "Visual Theme Editor for tailwind CSS & shadcn/ui components" with preset themes to start from and "advanced customisation for each aspect of your UI." The audience is frontend developers and designers working on a shadcn/ui codebase who want to see the change before they commit it, rather than a design-token pipeline for large organisations.

## How the editor and the exported theme relate

The repository is a Next.js application, not a library you import. The top-level layout shows app/, components/, store/, hooks/, lib/, db/, drizzle/ and a middleware.ts, which is the shape of a full web product: routes, a component tree, client state, a database layer with Drizzle migrations, and request middleware. The editor itself lives in that app, and the output is a theme definition you copy into your own project.

The package.json names the toolchain. The dev and build scripts use Next.js with the --turbopack flag, and dependencies include @dnd-kit packages for drag-and-drop, culori for colour handling, and @tiptap plus @lexical/react for rich text editing. There is also an AI layer: @ai-sdk/google, @ai-sdk/react, @google/generative-ai and the ai package. The .env.example confirms this with GOOGLE_API_KEY and GROQ_API_KEY entries, so the hosted product can generate or suggest theme changes. Those keys are not needed to browse presets; they are needed for the AI-assisted paths.

Two scripts are worth noting because they explain how presets are produced. generate-theme-registry runs tsx scripts/generate-theme-registry.ts followed by tsx scripts/generate-registry.ts, and it is wired into prebuild, so every production build regenerates the theme registry before Next.js compiles. minify-live-preview runs terser over public/live-preview.js and is wired into postbuild. The live preview is therefore a separate script that gets minified as part of the build, not a component compiled into the main bundle.

## Installing tweakcn locally and opening the editor

The README lists Node.js 18+ and npm, yarn or pnpm as prerequisites. The installation steps are a clone, an install, and a dev server. The README gives these commands directly:

```bash
git clone https://github.com/jnsahaj/tweakcn.git
cd tweakcn
npm install
npm run dev
```

After npm run dev, the README says to open http://localhost:3000 in a browser. The dev script is next dev --turbopack, so the server starts on port 3000 by default. At this point you have the editor UI, but the AI features and authentication will not work until environment variables are set.

The .env.example file defines what the app expects. BASE_URL defaults to http://localhost:3000, DATABASE_URL points at a Neon PostgreSQL instance, and there are OAuth pairs for GitHub and Google plus a BETTER_AUTH_SECRET. The comments in that file link to the Neon console, the better-auth installation docs, and the GitHub and Google OAuth setup pages. Copying .env.example to .env.local and filling those values is the step the file implies, though the README itself does not spell it out:

```bash
cp .env.example .env.local
```

If you prefer containers, the repository ships a docker-compose.yml with two services. The app service builds from the Dockerfile, maps port 3000, reads .env.local, and runs npx drizzle-kit push followed by npm run dev. The db service is postgres:15 with user postgres, password postgres and database tweakcn on port 5432. The Dockerfile itself is a single-stage node:20-alpine image that runs npm install and then npm run dev, so the container serves the development server rather than a production build.

## Where tweakcn stops being the right tool

The Dockerfile is the clearest limitation. It runs npm run dev as its CMD, and docker-compose mounts the working directory with an anonymous volume over /app/node_modules. That is a development container. There is no production image, no multi-stage build, and no mention of a build output being served. If you want to self-host tweakcn for a team, you are assembling the production path yourself, and the README does not document one.

The environment file is the second constraint. Running the full application requires a Neon PostgreSQL connection string, a better-auth secret, GitHub and Google OAuth credentials, a Google API key, a Groq API key, and a Google Fonts API key. That is a lot of third-party accounts for a tool whose visible output is a block of CSS variables. The README does not document a mode that skips authentication or the database, so a stripped-down local instance is not described.

Version drift is the third. The repository topics list tailwindcss-v4, and the theme tokens tweakcn exports are tied to the Tailwind and shadcn/ui conventions of the version it targets. The README does not document a compatibility matrix, so if your project is on an older Tailwind major, the exported variables may not map cleanly onto your existing setup. There is also no documented rollback: once you paste a new theme into your project, reverting means having kept the previous values somewhere.

## tweakcn compared with editing the CSS variables by hand

The obvious alternative is the shadcn/ui theming page and a text editor. That approach has no dependencies at all: you edit the custom properties in your global stylesheet, reload, and look. It is faster to start and requires no account, no database and no API keys.

The difference is feedback. Hand-editing gives you a value and a reload; tweakcn gives you a control, a live preview and a preset to start from. The repository shows how much machinery sits behind that preview: a separate live-preview.js that is minified at build time, drag-and-drop for reordering, and colour utilities from culori. If you are changing one token, the text editor wins. If you are exploring a whole palette, contrast relationships and radius across many components, the visual loop is the point of the tool.

The second alternative is generating themes with an AI coding assistant. tweakcn also offers an AI path, but it is one feature inside an editor where you can see and adjust the result, rather than a one-shot prompt whose output you then have to inspect.

## Licence, maintenance and the cost of keeping up

The repository is licensed Apache-2.0. That is a permissive licence with an explicit patent grant and a requirement to preserve notices, but it applies to the code in the repository. The README says nothing about the licence of themes you create with the editor or of the preset themes shipped with it, so treat the status of the presets as unverified and read LICENSE before redistributing anything bundled.

On maintenance, the last push to the default branch was on 2026-09-03, which is recent. There are no retrieved releases, so there is no tagged version to pin against; the package.json version is 0.1.0 and the package is marked private. Upgrading means tracking the main branch, and the prebuild hook regenerates the theme registry on every build, so a change to the registry scripts can alter your build output without a version number changing.

The practical cost is the dependency surface. The package.json pulls in a Next.js app, a Drizzle database layer, better-auth, Polar checkout packages, TanStack Query and Table, two rich-text editors, and two AI SDKs. Running this locally for its editor is heavier than the output suggests. If you only need the exported theme, the hosted editor at tweakcn.com avoids carrying any of that.

## Conclusion

tweakcn is worth adopting if you ship shadcn/ui components and want to explore colour, radius and typography changes without hand-editing CSS variables, either through the hosted editor or by running the repository locally. Skip it if you need a production-grade multi-tenant theming backend: it is a Next.js app with Postgres, OAuth and AI keys, and the README documents no deployment or rollback path. Before committing, verify that your Tailwind major version matches the tokens tweakcn exports, and check the licence terms in LICENSE against how you plan to redistribute the generated theme.

## FAQ

### What is tweakcn?

tweakcn is a visual no-code theme editor for Tailwind CSS and shadcn/ui components, hosted at tweakcn.com. It offers preset themes and per-aspect customisation, and the repository is a Next.js application you can also run locally.

### How do I use tweakcn?

You can use the hosted editor at tweakcn.com, or run the repository locally with git clone, npm install and npm run dev, then open http://localhost:3000. The README's installation steps cover exactly those commands.

### Is tweakcn free?

The repository is licensed Apache-2.0 and the source is public, and the README does not describe a paid tier for the editor itself. The package.json does include Polar checkout dependencies, which suggests the hosted product has payment paths, but the README does not document pricing.

### What is the best shadcn theme generator?

tweakcn's own claim is that it targets the problem that shadcn/ui sites look the same, offering presets plus advanced customisation for each aspect of the UI. The README does not compare it against other generators.

## Sources

- [Issues](https://github.com/jnsahaj/tweakcn/issues)
- [jnsahaj/tweakcn on GitHub](https://github.com/jnsahaj/tweakcn)
- [License: Apache-2.0](https://github.com/jnsahaj/tweakcn/blob/main/LICENSE)
- [Project website](https://tweakcn.com)
- [README](https://github.com/jnsahaj/tweakcn/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jnsahaj-tweakcn