Skip to content

Files

Latest commit

5210f1b · Dec 23, 2024

History

History
173 lines (119 loc) · 6.74 KB

README.md

File metadata and controls

173 lines (119 loc) · 6.74 KB

portal

A clojure tool to navigate through your data.

cljdoc Clojars Project VS Code Extension Version Get help on Slack

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.

London Clojurians Demo

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.5"}}}'

or for a web clojurescript >= 1.10.773 repl, do:

clj -Sdeps '{:deps {djblue/portal {:mvn/version "0.58.5"}
                    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.5"}
                    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.5"}}}'

or for a lein project.clj, add:

{:profiles {:dev {:dependencies [[djblue/portal "0.58.5"]]}}}

or as a global profile, add to ~/.lein/profiles.clj:

{:portal {:dependencies [[djblue/portal "0.58.5"]]}}

Note

If you add Portal to a profile other than :dev, when starting a REPL start it with with-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.