A component for rendering React components with editable source and live preview
Clone or download
Latest commit 0f596ed Aug 23, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
demo deprecated demo babel config Feb 5, 2018
docs Move prop-types to peerDependencies (#116) Dec 7, 2017
src explicit navigator check for codemirror issue Jun 10, 2018
test/client Updating lint, fixing error trapping, polyfilling map/set Oct 2, 2017
.babelrc Fix build + es + prop-types (#119) Jan 27, 2018
.editorconfig Bringing build/test/lint setup up to our modern standards. Will fix l… Sep 18, 2015
.eslintignore Bringing build/test/lint setup up to our modern standards. Will fix l… Sep 18, 2015
.eslintrc-base Updating lint, fixing error trapping, polyfilling map/set Oct 2, 2017
.eslintrc-node Updating lint, fixing error trapping, polyfilling map/set Oct 2, 2017
.eslintrc-react Updating lint, fixing error trapping, polyfilling map/set Oct 2, 2017
.eslintrc-react-test Updating lint, fixing error trapping, polyfilling map/set Oct 2, 2017
.gitignore Fix build + es + prop-types (#119) Jan 27, 2018
.npmignore.publishr Fix build + es + prop-types (#119) Jan 27, 2018
.travis.yml Fix publishr config; update yarn.lock; fix travis.yml and update (#133) Aug 23, 2018
CHANGELOG.md update changelog Jun 11, 2018
CONTRIBUTING.md adding code of conduct for contributing Aug 22, 2016
DEVELOPMENT.md Update publish steps in DEVELOPMENT Feb 25, 2016
LICENSE Fix build + es + prop-types (#119) Jan 27, 2018
README.md Add react-live/component-playground comparison (#103) Sep 25, 2017
karma.conf.coverage.js Bringing build/test/lint setup up to our modern standards. Will fix l… Sep 18, 2015
karma.conf.dev.js Bringing build/test/lint setup up to our modern standards. Will fix l… Sep 18, 2015
karma.conf.js Move loaders for css files to devDependencies (#101) Sep 21, 2017
package.json 3.2.1 Aug 23, 2018
webpack.config.coverage.js Fix build + es + prop-types (#119) Jan 27, 2018
webpack.config.dev.js build Oct 6, 2015
webpack.config.js Fix build + es + prop-types (#119) Jan 27, 2018
webpack.config.test.js Upgrade lodash to v4.13 May 31, 2016
yarn.lock Fix publishr config; update yarn.lock; fix travis.yml and update (#133) Aug 23, 2018

README.md

Build Status

component-playground

A component for rendering React Components and ES6 code with editable source and live preview

Component Playground

Demo

https://formidable.com/open-source/component-playground/

Installation

npm install component-playground

Set up

In the head of your html document, either add the css files from the demo or from a CDN like:

<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/codemirror/5.0.0/codemirror.min.css"/>
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/codemirror/5.0.0/theme/monokai.min.css"/>

In your JSX, require the component and use it like this:

'use strict';

var React = require('react/addons');
var ReactDOM = require('react-dom');
var Playground = require('component-playground');
var Button = require('./components/button');

var componentExample = require("raw!./examples/component.example");

var Index = React.createClass({
  render() {
    return (
      <div className="component-documentation">
        <Playground codeText={componentExample} scope={{React: React, Button: Button}}/>
      </div>
    );
  }
});

ReactDOM.render(<Index/>, document.getElementById('root'));

Props

codeText

React.PropTypes.string.isRequired

codeText takes a string of JSX markup as its value. While you can just pass it a string, I find it is easier to make a separate file and use Webpack's raw loader to load in the raw source. In the example above I use the .example extension, and an examples folder to organize my samples.

An example file would look like:

<Button style={{background: '#3498db'}}>Hi</Button>

scope

React.PropTypes.object.isRequired

When evaluating the JSX, it needs to be provided a scope object. At the very least, React needs to be provided to the scope, if any custom tags aren't being used. See below:

<Playground codeText={componentExample} scope={{React: React}}/>

Any module/component that is used inside the playground needs to be added to the scope object. See /demo for an example of how this works.

theme

React.PropTypes.string

String specifying which CodeMirror theme to initialize with. Defaults to 'monokai'.

collapsableCode

React.PropTypes.bool

Allows the user to collapse the code block.

<Playground collapsableCode={true} codeText={componentExample} scope={{React: React}}/>

initiallyExpanded

React.PropTypes.bool

Makes collapsable code block initially expanded.

<Playground
  collapsableCode={true}
  initiallyExpanded={true}
  codeText={componentExample}
  scope={{React: React}}/>

docClass

React.PropTypes.node

A component class that will be used to auto-generate docs based on that component's propTypes. See propDescriptionMap below for how to annotate the generate prop docs.

<Playground docClass={MyComponent} codeText={componentExample} scope={{React: React}}/>

propDescriptionMap

React.PropTypes.string

Annotation map for the docClass. The key is the prop to annotate, the value is the description of that prop.

<Playground
  docClass={MyComponent}
  propDescriptionMap={{
    collapsableCode: "Allows the user to collapse the code block"
  }}
  codeText={componentExample}
  scope={{React: React}}/>

es6Console

React.PropTypes.bool

Turns preview into a simple console for testing out ES6 code. Use console.log() in the playground to generate output.

<Playground
  es6Console={true}
  codeText={es6Example} />

noRender

React.PropTypes.bool

Defaults to true. If set to false, allows you bypass the component-playground's component wrapper and render method. You can use this option to write higher order components directly in your example code and use your own Render method. NOTE: This option requires that the React.render method be in your code

var ComponentExample = React.createClass({
  render: function() {
    return (
        <p>Hi</p>
    )
  }
});

React.render(<ComponentExample/>, mountNode);

Comparison to react-live

There are multiple options when it comes to live, editable React component environments. Formidable actually has two first class projects to help you out: component-playground and react-live. Let's briefly look at the libraries, use cases, and factors that might help in deciding which is right for you.

Here's a high-level decision tree:

  • If you want fast and easy setup and integration, then component-playground may be the ticket!
  • If you want a smaller bundle, SSR, and more flexibility, then react-live is for you!

Here are the various factors at play:

  • Build: component-playground uses babel-standalone, react-live uses bublé. (Note: react-live might make transpiler customizable in the future).
  • Bundle size: component-playground has a larger bundle, but uses a more familiar editor setup. react-live is smaller, but more customized editor around prism.
  • Ease vs. flexibility: react-live is more modular/customizable, while component-playground is easier/faster to set up.
  • SSR: component-playground is not server-side renderable, react-live is.
  • Extra features: component-playground supports raw evaluation and pretty-printed output out-of-the-box, while react-live does not.
  • Error handling: component-playground might have more predictable error handling than react-live in some cases (due to react-dom, although this might change with React 16).