Awesome
portal
A clojure tool to navigate through your data.
<a target="_blank" href="https://djblue.github.io/portal/?content-type=application/edn&content-url=https://raw.githubusercontent.com/djblue/portal/gh-pages/docs.edn"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/1986211/196015562-238cf450-6467-451c-a985-04c7a9b49dba.png"> <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/1986211/196015567-74ba9153-341a-4fd7-be47-2c26f0c88c2e.png"> <img src="https://user-images.githubusercontent.com/1986211/196015562-238cf450-6467-451c-a985-04c7a9b49dba.png"> </picture> </a>The portal UI can be used to inspect values of various shapes and sizes. The UX will probably evolve over time and user feedback is welcome!
For an in-depth explanation of the UI, you can jump to the UI docs.
Demo
To get an overview of the Portal UI and workflow, checkout the following recording of a live demo I gave for London Clojurians.
<a target="_blank" href="https://www.youtube.com/watch?v=Tj-iyDo3bq0"> <img src="https://img.youtube.com/vi/Tj-iyDo3bq0/hqdefault.jpg" alt="London Clojurians Demo" /> </a>More video presentations on Portal can be found here.
Usage
To start a repl with portal, run the clojure >= 1.10.0 cli with:
clj -Sdeps '{:deps {djblue/portal {:mvn/version "0.58.2"}}}'
or for a web clojurescript >= 1.10.773 repl, do:
clj -Sdeps '{:deps {djblue/portal {:mvn/version "0.58.2"}
org.clojure/clojurescript {:mvn/version "1.10.844"}}}' \
-m cljs.main
or for a node clojurescript >= 1.10.773 repl, do:
clj -Sdeps '{:deps {djblue/portal {:mvn/version "0.58.2"}
org.clojure/clojurescript {:mvn/version "1.10.844"}}}' \
-m cljs.main -re node
or for a babashka >=0.2.4 repl, do:
bb -Sdeps '{:deps {djblue/portal {:mvn/version "0.58.2"}}}'
or for a lein project.clj
, add:
{:profiles {:dev {:dependencies [[djblue/portal "0.58.2"]]}}}
or as a global profile, add to ~/.lein/profiles.clj
:
{:portal {:dependencies [[djblue/portal "0.58.2"]]}}
[!NOTE] If you add Portal to a profile other than
:dev
, when starting a REPL start it withwith-profiles +portal
. The+
is important.
or for Clojure CLR, checkout this example project,
or for examples on how to integrate portal into an existing project, look through the examples directory.
[!NOTE] Portal can also be used without a runtime via the standalone version.
API
Try the portal api with the following commands:
;; for node and jvm
(require '[portal.api :as p])
;; for web
;; NOTE: you might need to enable popups for the portal ui to work in the
;; browser.
(require '[portal.web :as p])
(def p (p/open)) ; Open a new inspector
;; or with an extension installed, do:
(def p (p/open {:launcher :vs-code})) ; jvm / node only
(def p (p/open {:launcher :intellij})) ; jvm / node only
(add-tap #'p/submit) ; Add portal as a tap> target
(tap> :hello) ; Start tapping out values
(p/clear) ; Clear all values
(tap> :world) ; Tap out more values
(prn @p) ; bring selected value back into repl
(remove-tap #'p/submit) ; Remove portal from tap> targetset
(p/close) ; Close the inspector when done
(p/docs) ; View docs locally via Portal - jvm / node only
[!WARNING] Portal will keep objects from being garbage collected until they are cleared from the UI.
Options
Options for portal.api/open
:
Option | Description | Default | Spec |
---|---|---|---|
:window-title | Custom window title for UI | "portal" | string? |
:theme | Default theme for UI | :portal.colors/nord | |
:value | Root value of UI | (atom (list)) | |
:app | Launch UI in Chrome app window | true | boolean? |
:launcher | Launch UI using this editor | #{:vs-code :intellij :emacs} | |
:editor | Enable editor commands, but use separate UI | #{:vs-code :intellij :emacs} | |
:port | Http server port for UI | 0 | int? |
:host | Http server host for UI | "localhost" | string? |
For more documentation, take a look through the docs.