Kushi is a complete styling and UI solution for ClojureScript.
This template demonstrates how to setup a project with Kushi, using shadow-cljs and Reagent. You can find most of the documentation and examples that you need to get started via comments in the src files of this project.
This template is based on shadow-cljs/browser-quickstart
The example kushi.edn features all the options (set to their defaults), with descriptive commentary. By design, this quickstart template includes all the relevant css to allow you to explore the design system, design tokens, semantic variants, and the entire kushi.ui library of pre-built components. In a real-world project, you may very well be using only a subset of these things, in which case you can aggressively elide different categories of css and reduce your bundle size. The comments in the kushi.edn file describe which options write kind of css.
git clone https://github.com/kushidesign/kushi-quickstart.git kushi-quickstart
cd kushi-quickstart
npm install
npx shadow-cljs watch appThis will begin the compilation of the configured :app build and re-compile whenever you change a file.
When you see a kushi report followed by a "Build completed." message (from shadow-cljs) your build is ready to be used.
[:app] Compiling ...
[:app] Using Kushi <version>
[:app] [Kushi <version>] - Writing 281 rules and 319 tokens.
[:app] Build completed. (176 files, 175 compiled, 0 warnings, 13.19s)You can view this app at http://localhost:8020.
The app is only a very basic skeleton. Please see shadow-cljs/browser-quickstart for more detailed info shadow-cljs-specific configuration options.
If you were to setup kushi manually, starting with the base shadow-cljs template, you would follow these 3 steps:
;; shadow-cljs configuration
{:source-paths
["src/dev"
"src/main"
"src/test"]
:dependencies
[[reagent "1.1.1"]
[design.kushi/kushi "1.0.0-a.19"] ; ! Kushi dependency
[binaryage/devtools "1.0.6"]]
:dev-http
{8020 "public"}
:cache-blockers
#{kushi.core kushi.stylesheet} ; ! Add these 2 namespaces to :cache-blockers entry.
:builds
{:app
{:target
:browser
:build-hooks
[(kushi.core/kushi-debug)
(kushi.stylesheet/create-css-file)] ; ! Kushi build hooks
:output-dir
"public/js"
:asset-path
"/js"
:modules
{:main
{:init-fn starter.browser/init}}}}};; This is a map with, at minimum, a `:css-dir` entry.
;; This must be relative to project root e.g "public/css" or "resources/public/css".
;; Please see the provided kushi.edn file for additional options.
{:css-dir "public/css"}<!-- The two tags with comments above them must be included for kushi to work. -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<!---
The value of the `href` in the link tag below needs to
align with the provided value in your kushi.edn config file.
At minimum, you must specify a value for :css-dir in your kushi.edn.
You can optionally specify a value for :css-filename.
The default value for :css-filename will be `kushi.css`.
-->
<link rel="stylesheet" href="./css/kushi.css" type="text/css">
<title>Kushi Quickstart</title>
</head>
<body>
<noscript>You need to enable JavaScript to run this app.</noscript>
<div id="app"></div>
<script src="./js/main.js"></script>
</body>
</html>At the very bottom of your app's main ns, you may want to include:
(when ^boolean js/goog.DEBUG
(inject!))This will inject the same stylesheet that kushi writes to disk into your browser, during development builds. You may not need or want to do this but if you are experiencing visual jankiness on reloads when developing, this can help.
Please see src/main/starter/browser.cljs, src/main/starter/badges.cljs, and src/main/starter/shared_styles.cljs for details on requiring and using various kushi functionality.