Devcards For React

Browser Driven Component Development

Introduction

React Cards is a library that aims to bring a visual REPL-like experience for React Developers when creating components.

It is heavily inspired by Bruce Hauman’s excellent Devcards project, which enables ClojureScript developers to quickly write components and gain visual feedback.

The benefits are clear once we see Devcards in full effect. First and foremost creating a Component inside an existing application is hard and is limited by the surrounding constraints. Everyone creating UI components inside a full fledged application knows how complex this can be. One solution is to use something like jsfiddle or codepen, but this suboptimal, as you still might need specific css classes or other modules that you can’t access when taking this route.

React Card is driven by the code, not static requirements defined via configs for example. React Cards tries to bring a similar Devcard experience to React developers, opening up the possibility to quickly test the look and feel as well as the behavior of a component. Furthermore enabling developers to write markdown and even run tests against the component, displaying the test results as a React component itself.

React Cards in action

This approach has many benefits. A component with multiple possible states can be difficult to test and document. With React Cards we can display the component in many different states along with documentation and tests to ensure nothing breaks while we’re working on the component.

Bruce Hauman created a short screen cast to highlight the benefits and effectiveness of this approach in Devcards.

Getting Started

Clone the React Cards repository https://github.com/steos/reactcards and run

npm install
npm run example

React Cards will be available at http://localhost:8080

To see React Cards in action, go to the example directory and start experimenting.

Writing Cards

Take a look at the examples folder. There are several cards you can edit on the fly.

import React from 'react'
import cards from 'reactcards'
import {Foo, Bar} from './components'

const demo = cards('demo')

abc.card(<Foo message="yo" />, 'here is  a simple example')

demo.card(
    `## markdown doc
  you can use markdown for card documentation
  - foo
  - bar`,
    <Foo message="hello"/>
)

demo.card(<Foo message="hello world"/>)

demo.card(<Bar/>, {title: 'a bar card'})

React Cards

Creating a Stateful Component

import React from 'react'
import cards from 'reactcards'
import {StatefulComponent} from './components'

const demo = cards('demo')

demo.card(
    `## Counter

  This is a stateful counter. If you change the value prop
  in the source file it will not update because the new prop will be ignored
  and instead the component local state is rendered.

  Implement *componentWillReceiveProps* and override the component local state
  if you want this to work as expected.`,

    <StatefulCounter value={42}/>
)

React Cards with Stateful Compoenent

Creating a Stateful Component with Undo/Redo

We can even add undo/redo capabilities to a React Card.

import React from 'react'
import cards from 'reactcards'
import {StatefulComponent} from './components'

const demo = cards('demo')

demo.card(
    `## Undo/Redo
  Same example as before but with undo/redo controls added by the card.`,

    (state) =>
        <StatelessCounter
            value={state.get()}
            inc={() => state.update(x => x + 1)}
            dec={() => state.update(x => x - 1)}/>,
    {
        init: 1337,
        history:true,
    }
)

React Cards with undo/redo

Writing Tests

You can write your tests using enzyme or chai for example. Take a look at the test folder inside examples to see reference enzyme/chai tests.

// your test file...
import {assert} from 'chai'

export function testAdd() {
    assert.equal(1 + 1, 2)
}

export function testFail() {
    assert.isTrue(false)
}

// your reactcards file
import React from 'react'
import cards from 'reactcards'
import someTests from './testFile'

const demo = cards('demo')

demo.test(someTests, {title:'simple tests'})

You can write tests in a separate folder or write them directly inside a card. The first approach enables us to reuse the test in a different setting. This means we can reuse the same tests for both, React Cards as well as cli test. More on this in a separate post.

React Cards Tests

Ingredients

React Cards itself only consists of a minimal set of components and a simplified store for handling namespaces and cards. The weight lifting is mainly done by the improved react-hot-loader 3 by Dan Abramov and enzyme and chai for testing.

Outro

This easiest way is to checkout https://github.com/steos/reactcards directly and experiment with the possibilities. Special thanks to Nik Graf for the inspiration.

React Cards is work in progress. If you have any questions or feedback please connect on twitter or connect with Stefan Oestreicher on twitter or leave a comment here.