{"id":19942069,"url":"https://github.com/day8/re-frame-debux","last_synced_at":"2025-08-20T03:31:14.527Z","repository":{"id":54254578,"uuid":"123882717","full_name":"day8/re-frame-debux","owner":"day8","description":"A fork of debux for tracing re-frame code (for eventual consumption by re-frame-10x)","archived":false,"fork":false,"pushed_at":"2021-11-04T22:30:40.000Z","size":2722,"stargazers_count":44,"open_issues_count":6,"forks_count":7,"subscribers_count":11,"default_branch":"master","last_synced_at":"2024-12-05T18:38:14.893Z","etag":null,"topics":["clojurescript","debugging","re-frame","tracing"],"latest_commit_sha":null,"homepage":"","language":"Clojure","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/day8.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"mike-thompson-day8"}},"created_at":"2018-03-05T07:40:01.000Z","updated_at":"2024-11-16T01:31:28.000Z","dependencies_parsed_at":"2022-08-13T10:10:26.003Z","dependency_job_id":null,"html_url":"https://github.com/day8/re-frame-debux","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/day8%2Fre-frame-debux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/day8%2Fre-frame-debux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/day8%2Fre-frame-debux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/day8%2Fre-frame-debux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/day8","download_url":"https://codeload.github.com/day8/re-frame-debux/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230388131,"owners_count":18217755,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["clojurescript","debugging","re-frame","tracing"],"created_at":"2024-11-13T00:11:34.848Z","updated_at":"2024-12-19T06:09:28.255Z","avatar_url":"https://github.com/day8.png","language":"Clojure","funding_links":["https://github.com/sponsors/mike-thompson-day8"],"categories":[],"sub_categories":[],"readme":"\u003c!-- [![CI](https://github.com/day8/re-frame-debux/workflows/ci/badge.svg)](https://github.com/day8/re-frame-debux/actions?workflow=ci)\n[![CD](https://github.com/day8/re-frame-debux/workflows/cd/badge.svg)](https://github.com/day8/re-frame-debux/actions?workflow=cd)\n[![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/day8/re-frame-debux?style=flat)](https://github.com/day8/re-frame-debux/tags) \n[![GitHub pull requests](https://img.shields.io/github/issues-pr/day8/re-frame-debux)](https://github.com/day8/re-frame-debux/pulls)\n\n--\u003e\n[![Clojars Project](https://img.shields.io/clojars/v/day8.re-frame/tracing?style=for-the-badge\u0026logo=clojure\u0026logoColor=fff)](https://clojars.org/day8.re-frame/tracing)\n[![GitHub issues](https://img.shields.io/github/issues-raw/day8/re-frame-debux?style=for-the-badge\u0026logo=github)](https://github.com/day8/re-frame-debux/issues)\n[![License](https://img.shields.io/github/license/day8/re-frame-debux?style=for-the-badge)](https://github.com/day8/re-frame-debux/blob/master/LICENSE)\n\n# re-frame-debux\n\n[debux](https://github.com/philoskim/debux) is [@philoskim's](https://github.com/philoskim) useful and novel library for tracing Clojure and ClojureScript code, form by form.\n\nThis library, **re-frame-debux**, is a fork of **debux**, that repurposes it for tracing the ClojureScipt code in re-frame event handlers, for later inspection within [re-frame-10x](https://github.com/Day8/re-frame-10x).\n\nThis fork contains a few substantial extension/modifications to debux and, longer term, we would like to investigate merging them back into mainline debux, but the changes we needed to make required quite deep surgery, so in the interests of time, and getting a proof of concept out the door, we started off with a fork.\n\n## Show Me\n\nHere's what the trace looks like in `re-frame-10x`:\n\n![Estim8 demo](https://github.com/Day8/re-frame-10x/blob/master/docs/images/estim8-demo.png)\n\n\n## Status\n\nAlready useful!! But it is still a work in progress and there'll likely be little annoyances and bugs, perhaps even big ones.\n\nAs always, if you run into any issues, please open an issue and we can try and help. We are also looking for collaborators on this interesting project. There's so much potential. (Beware, zippers and macros lurk).\n\nSharp edges include:\n  - Operations like `map` or `for` operating on big sequences will generate too much trace.  That will be a problem within `re-frame-10x`. Don't enable tracing for event handlers which have that sort of processing. Not yet. [See issue #6](https://github.com/Day8/re-frame-debux/issues/6)\n\n## Prerequisites\n\n* clojure 1.8.0 or later\n* clojurescript 1.9.854 or later\n\n\n## How to use\n\n`re-frame-debux` provides two macros:\n\n* `fn-traced`  (use instead of `fn`)\n* `defn-traced`  (use instead of `defn`)\n\nUse them like this when registering event handlers:\n\n```clojure\n(ns my.app\n  (:require [day8.re-frame.tracing :refer-macros [fn-traced defn-traced]]))\n\n(re-frame.core/reg-event-db\n  :some-event\n  (fn-traced [db event]     ;; \u003c--- use `fn-traced` instead of `fn`\n     ; ... code in here to be traced\n     ))\n```\n\nor:\n\n```clojure\n(defn-traced my-handler   ;; \u003c--- use `defn-traced` instead of `defn`\n  [coeffect event]\n  ;; ... code in here to be traced\n  )\n\n(re-frame.core/reg-event-fx\n   :some-event\n   my-handler)\n```\n\n## Option 1: Two libraries\n\n**In development,** you want to include the `day8.re-frame/tracing` library. When you use a `day8.re-frame.tracing/fn-traced` or `day8.re-frame.tracing/traced-defn` from this library, it will emit traces to re-frame's tracing system, which can then be consumed by [re-frame-10x](https://github.com/Day8/re-frame-10x).\n\n**In production,** you want to include the `day8.re-frame/tracing-stubs` library. This has the same public API as `tracing` (`day8.re-frame.tracing/fn-traced`, `day8.re-frame.tracing/traced-defn`), but the macros simply delegate to the core `fn` and `defn` macros.\n\nWith this setup, your use of both macros will have zero runtime and compile time cost in production builds, and are able to be turned off at dev time too via the Closure define.  This ensures that you can leave your code instrumented at all times, but not pay any costs in production.\n\n### Why two libraries?\n\nIt is technically possible to use the `day8.re-frame/tracing` library in your production builds. Under advanced compilation, the Closure define should ensure that dead code elimination (DCE) works to remove the traced version of the function from your final JS file. We verified that the traced function JS was removed, but had concerns that other required namespaces may not be completely dead code eliminated. Have a tracing-stubs makes it impossible for DCE to fail, because there is no dead code to be eliminated.\n\n## Option 1: Installation\n\n**First, please be sure to read the \"Two libraries\" section immediately above for background.**\n\nTo include *re-frame-debux* in your project, simply add the following to your *project.clj* development dependencies:\n\n```\n[day8.re-frame/tracing \"0.5.3\"]\n```\n\nand this to your production dependencies (make sure they are production only):\n\n```\n[day8.re-frame/tracing-stubs \"0.5.3\"]\n```\n\nAdd Closure defines to your config to enable re-frame tracing + the function tracing:\n\n```\n:cljsbuild    {:builds {:client {:compiler {:closure-defines {\"re_frame.trace.trace_enabled_QMARK_\" true\n                                                              \"day8.re_frame.tracing.trace_enabled_QMARK_\"  true}}}}}}\n```\n\n\n## Option 2: Namespace Aliases with shadow-cljs\n\nRequires version 0.5.5 or greater.\n\nThe `day8.re-frame.tracing-stubs` ns is also available in the main package so\nthat if you are using shadow-cljs use `:ns-aliases` in a shadow-cljs build\nconfig to achieve the same result as option 1:\n\n```clojure\n{:builds\n {:app\n  {:target :browser\n   ...\n   :release\n   {:build-options\n    {:ns-aliases\n     {day8.re-frame.tracing day8.re-frame.tracing-stubs}}}}}\n\n```\n\nThis redirects every `(:require [day8.re-frame.tracing :as x])` to use the\nstubs instead in a release build and the development build just uses the\nregular code.\n\n## Resolving macros with Cursive\n\nYou can instruct [Cursive](https://cursive-ide.com) to treat the `fn-traced` and `defn-traced` macros like their standard `fn` and `defn` counterparts by [customising symbol resolution](https://cursive-ide.com/userguide/macros.html).\n\n\u003cimg width=\"500px\" src=\"doc/img/cursive-1.png\" alt=\"Resolve day8.re-frame.tracing/fn-traced as...\"\u003e\n\n\u003cimg width=\"500px\" src=\"doc/img/cursive-2.png\" alt=\"Resolve as... Specify...\"\u003e\n\n\u003cimg width=\"500px\" src=\"doc/img/cursive-3.png\" alt=\"Enter var name cljs.core/fn, include non-project files\"\u003e\n\n\n## Testing\n\nAs the macros are in clojure (not cljs) tests are run via `lein test`\n\n## License\nCopyright © 2015--2018 Young Tae Kim, 2018 Day 8 Technology\n\nDistributed under the Eclipse Public License either version 1.0 or any later version.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fday8%2Fre-frame-debux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fday8%2Fre-frame-debux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fday8%2Fre-frame-debux/lists"}