DevTools for re-frame

This summer, we worked on a project that was focused on improving the developer experience with re-frame. We want to give an overview of the tool and summarize our contributions in the following post.

The Joy of Debugging

How often do you print something to the console? I do it quite often. My application does not work as expected and I need to go into various places in the code to figure out what is causing the problem. Some piece of data has an incorrect value, but which one is it? Debugging is hard, but luckily, we can build tools to make it easier. The key is to present the application data in a clear and browsable form. We want coding to be more enjoyable so that we spend less time on fixing bugs and more on building things.

Our Summer

Thanks to getting a grant from RGSoC, we had the opportunity to work on a dev tool for re-frame, called re-frame trace. It was a great way of learning ClojureScript while working on a project that we will be using for future projects ourselves. As we were new to re-frame, we talked to a couple of people who had used it before so that we could get a better understanding of the user needs.

What is re-frame?

re-frame is a ClojureScript framework for building single-page applications with Reagent. If you’re from the JavaScript world, you can see that re-frame has a similar spirit to Redux. It manages the data flow through your application and enables a clear separation of concerns. Especially when working with large application state, re-frame adds a lot of value to the developer experience.

What is re-frame trace?

Inspired by redux-devtools, re-frame trace is a tracing panel developed for debugging re-frame applications. When enabled for development, it is being injected into the DOM of the main application and displays data for dispatched events, subscriptions, reagent renderings and re-frame internals. Each trace has some metadata and a performance value in milliseconds.

What did we achieve?

When we started, the basic architecture and data already existed. The challenge lied in finding a clean and easily understandable way of presenting the data. The tool generated a lot of traces which quickly felt overwhelming as a new user. We wanted to make the tool adaptable to the developer’s needs. The image below gives a first impression of the changes we made.

So what are our major contributions?

• Filter Improvements: The developer has multiple options to filter for the information he needs to focus on. He can search for traces containing one or more specific keywords. In cases when performance is important, it is possible to add a filter that shows traces that took longer than a specific number of milliseconds. Four general trace categories help to reduce the amount of traces that are being displayed depending on the use case.
• App-State Visualization: Using the formatting that cljs-devtools provides, we were able to add a new tab to the tracing window that displays the current values in the app state.
• Usability Improvements: The tracing window can be smoothly adapted in width and details can be expanded and collapsed for individual traces or for all at once. In a nutshell, we were able to present the traces in a clean and extendable way so that the developer is not overloaded with too much information at once.
• Documentation: We wrote documentation for how to set up the tracing tool for re-frame projects and added a section to help developers set up the project for development.

What can you do with re-frame trace?

We put together three exemplary scenarios for which re-frame trace can be used.

Scenario 1: I want to see all events including dispatch values that have been triggered.
(click here to enlarge gif)

Scenario 2: I only want to see events for checking todos that took longer than 5 milliseconds.
(click here to enlarge gif)

Scenario 3: I want to inspect the current values of the app-state.
(click here to enlarge gif)

Future ideas

During our project, we coordinated with Daniel Compton and Mike Thompson to understand the vision for the tracing tool more clearly. The idea is to see re-frame trace as a dashboard that can be adapted to the needs of individual developers giving more insight into their re-frame applications.

Try out re-frame trace!

Tell us about your developer experience on Clojurians Slack where you can find us as daiyi and saskia or open a github issue for bugs and ideas!

Some Thoughts

Is it already the beginning of August? That’s what my calender says, I’m not sure if I can believe it though. The last weeks have been filled with coding, exchanging ideas with my team and organizing our calenders. So far, our blog has not been able to keep up with the flood of knowledge that is accumulating in our heads. It’s time to change that! Here are some thoughts on our current state and my intention for this space.

Writing is fun. But writing is also time consuming. I know it’s a matter of practice, so let’s make it a goal for this week! There are so many ways of filling this blog with life. Personal status updates, code walk-throughs or my latest decision of learning yet another

(nth ["language" "dance style" "instrument" "random skill"] (rand-int 4))

I see writing as my break from coding. The empty page will be there patiently waiting for me to fill it with letters when my brain is unable to understand why my browser console won’t spare me with these beautiful red glowing stacktraces.

I thought a lot about what a good outcome of this project would look like for me. After gathering all of the thoughts that have been running through my mind, I found my personal goals for this summer:

Goal of Improving my programming skills

(->> (repeat "coding! ") (take (rand-int 10000)) (reduce str) str/trim)

Big Picture. I realized that I often fall into the trap of focusing too strongly on the code details. I easily understand what’s happening inside of a function, but seeing the bigger picture takes more time. I want to bring more awareness to zooming out every once in a while to understand which part of the system is being affected by what I’m working on. This also helps to realize early on if something is worth following through. Keep in mind to avoid bikeshedding and identify challenges and blockers early on!

Sense for Taste. A conversation with one of our coaches highlighted the importance of reflecting on one’s own practices and figuring out how things are done ideally. Look at how other people approach problems and identify which patterns they use. Try out different solutions and write down what worked well and what didn’t. Make reading code a habit, there are so many amazing publicly available projects out there!

Simplicity. Learn how to find simple solutions. Be aware when writing entangled code that is difficult to grasp for others and yourself and start to refactor. Identify the next step and reflect on its importance. Thinking of simplicity in the Clojure world is inevitably linked to Rich Hickey’s talk Simple Made Easy).

Experience. Writing code can be the most fun and also the most painful part of being a programmer. I love the feeling of getting in the flow and every time I get to write code on a regular basis, I’m able to see my progress within short periods of time. It’s thrilling to see new ways of thinking developing that gradually help me to improve my code quality. On top of that, understanding how and why the tooling works the way it does is of tremendous value. Nobody likes to be blocked by things that are related with tooling.

Goal of Creating a Knowledge Base

For me, there’s something exciting about organizing knowledge. I literally safe everything of importance that I hear or read about. Which usually leads to a bunch of markdown files full of good stuff sitting on my hard drive. Not having to remember all the little details has helped me in many situations, especially in my work life. I want to work on the presentation and access of this knowledge so it can be of use not only for myself, but also for others. Looking at this project, I have two different ideas in mind:

Guides. Writing guides containing a comprehensive summary of information needed in order to understand a certain technology or pattern.

Resources. There is so much good learning material out there, which makes it challenging to get an overview. Especially for beginners, it often is not evident where to start and how to set priorities. I like the idea of creating overviews. A great example is the collection of Clojure resources that has been quite useful for me in the past. At the moment, we get to learn about so many things on a daily basis, which gives me the opportunity to create my own overview of gathered resources and personal reflections. At some point, I intend to make a post about all the resources we used during the project pointing people to the ones that might be most useful for them based on their level of experience.

Goal of Making Writing a Habit

I will use this opportunity to learn how to break things down and continually write a bit every day. Instead of gathering tons of information over weeks, it’s better to get my thoughts out on more specific chunks and in real time. One of my intentions is to learn how to collect the most basic information needed in order to understand how to do something. For example: What are the most important things I need to know so that I can build my own application with reagent? Remember: more writing, less perfectionism.

Goal of Good Communication

Communication has such a big influence on my productivity and mood. I’m becoming more and more aware of my use of language and seeing its impact . It actually started with the Clojure community in Berlin. After attending ClojureBridge, I was bursting with energy and motivation. I wanted to understand what made this workshop experience so special for me and realized next to many other things like being welcoming, dedicated and supportive, it was the positive language of the ClojureBridge organizers and coaches that left me with a feeling of excitement.

It’s really happening. After many months of anticipation, we’re so close to finally start working on re-frame.

Levels of excitement are raising.
Preparations are being made.
Informations are getting exchanged.

Only four more days!

It fascinates me to realize how many people put time and energy into making this experience possible. Five months ago, my job ended unexpectedly. The next day, I saw that applications for Rails Girls Summer of Code were opening. What a happy coincidence. Through a common friend, Chris and I got connected and things started to fall into place. We talked to many people and found six amazing coaches that were willing to support us throughout the project.

The Clojure community in Berlin had a big positive influence on both of us, which made the decision for a particular project quite easy. We wanted to deepen our experience with ClojureScript and contribute to the community that has welcomed us in such a beautiful way.

This morning, we talked to the project maintainers for the first time. It was a great way to get a bit more of a bigger picture. They told us that re-frame emerged out of the intention to create richer and more sophisticated clients, which puts more stress on the client side of things than usual.

I always ask myself, how do people start larger projects? What does the first commit look like? Well, I am going to tell you, because I could not resist to have a look at it. Here are the first lines of re-frame:

+re-frame
+========
+
+A Reagent Framework

Just thinking about how these four simple lines grew into what the framework is today simply blows my mind.

Coming from two different sides, I’m happy to be working together with Chris on this. She has a strong background in JavaScript and React and I have a bit of practical experience with Clojure. It feels like a really good fit. Our plan for the first couple of days is getting familiar with the ClojureScript toolings and creating some sample applications with Reagent and re-frame.

I’m wondering, what will the next three months bring for us? The thought alone puts a smile on my face. We will keep you updated about all the bumps and breakthroughs we will experience. I am very happy and grateful to be part of a team full of inspiring people. Let’s see what we can create together!

One of our goals for the summer is to write more, so we are aggressively setting up a whole new blog for our dedicated developer diary as we learn about clojure/clojurescript, framework development, and open source contribution! Super excited to start working on re-frame next week (I can’t believe there’s only a week left, what happened to June??)

;; [silent screaming]
(println "hello world! \o/")

<3, chris