react-blockly


A React library for embedding Blockly, the visual programming editor from Google.

This is a continuation of PatientsLikeMe's react-blockly-component project. This new version utilizes Google's official Blockly npm packages in addition to other modernizations.

Features:

* Provides a hook as well as a function component for ease of use + flexibility
* Supports the JSON toolbox format
* Automatically propagates prop updates to Blockly
* Provides callbacks for workspace injection, disposal, changes, and XML import errors
* Automatically generates workspace XML, debounced for performance

VERSION 7 IS A COMPLETE REWRITE

This is the README for react-blockly version 7. If you're using the old class-based components, you will want to look at the version 6 readme instead: https://github.com/nbudin/react-blockly/blob/v6-stable/README.md

The breaking changes in react-blockly 7 are:

* All components except BlocklyWorkspace have been removed
* A hook for embedding Blockly in custom DOM has been added
* The custom JSON format for toolbox has been removed in favor of Blockly's official toolbox JSON format
* React 16.8 or higher is required
* immutable.js has been removed

Example usage

FernandoVazZ has made an example React app that shows how to set up react-blockly as well as how to create custom blocks for use in it: https://github.com/FernandoVazZ/reactblockly-customblocks/

Thanks so much Fernando!

Help wanted!

I wrote react-blockly for an internal tool when I worked at PatientsLikeMe, Inc. I no longer maintain this tool, and I don't even have access to it anymore. I also don't have any actual project that uses react-blockly anymore.

I'd love to find maintainers for this package who actually use it. In particular, some things I would love to have help with are:

* A test suite
* Better documentation
* More examples

If you are interested in working on any of those things, please let me know! Additionally, if you're interested in taking over maintainership of this package entirely, I'd be happy to talk to you about that.

Installation

To add react-blockly to a React app that uses npm, run:

``bash
npm install --save react-blockly
`

To add react-blockly to a React app that uses yarn, run:

`bash
yarn add react-blockly
`

How to use

You can use react-blockly as either a component or a hook. Embedding a component is often more
straightforward and plugs into your app easily. On the other hand, using the hook can give you
more control over exactly how Blockly is rendered.

$3

Write import { BlocklyWorkspace } from 'react-blockly'; in your code and use BlocklyWorkspace as a component.

Example:

`jsx
import { BlocklyWorkspace } from 'react-blockly';

function MyBlocklyEditor() {
const [xml, setXml] = useState();

return (
className="width-100" // you can use whatever classes are appropriate for your app's CSS
toolboxConfiguration={MY_TOOLBOX} // this must be a JSON toolbox definition
initialXml={xml}
onXmlChange={setXml}
/>
)
}
`

$3

Write import { useBlocklyWorkspace } from 'react-blockly'; in your code and use this hook to inject a Blockly workspace into your rendered components.

Example:

`jsx
import { useBlocklyWorkspace } from 'react-blockly';

function MyBlocklyHookEmbed() {
const blocklyRef = useRef(null);
const { workspace, xml } = useBlocklyWorkspace({
ref: blocklyRef,
toolboxConfiguration: MY_TOOLBOX, // this must be a JSON toolbox definition
initialXml: xml,
});

return (