From a62cc2bfb508273fc294c2b9d0bc3de6b3936239 Mon Sep 17 00:00:00 2001 From: jmarler Date: Sat, 14 Dec 2024 12:46:30 +0000 Subject: [PATCH] Update documentation --- README.md | 67 ++++++++++++++++------- docs/README.md | 26 ++++----- docs/SUMMARY.md | 9 ++-- docs/components/Image.md | 4 +- docs/components/Styles.md | 38 +++++++------- docs/components/Text.md | 2 +- docs/components/TextInput.md | 2 +- docs/guides/Debugging_With_Duktape.md | 2 +- docs/guides/Getting_Started.md | 24 +++++---- docs/guides/Integrating_Your_Project.md | 42 +++++++++++---- docs/guides/Running_the_Examples.md | 70 ------------------------- 11 files changed, 136 insertions(+), 150 deletions(-) delete mode 100644 docs/guides/Running_the_Examples.md diff --git a/README.md b/README.md index 09756295..709873fe 100644 --- a/README.md +++ b/README.md @@ -2,48 +2,75 @@ > Write cross-platform native apps with React.js and JUCE -React-JUCE (formerly named Blueprint) is a hybrid JavaScript/C++ framework that enables a [React.js](https://reactjs.org/) frontend for a [JUCE](http://juce.com/) application or plugin. It provides an embedded, ES5 JavaScript engine via [Duktape](http://duktape.org/), native hooks for rendering the React component tree to `juce::Component` instances, and a flexbox layout engine via [Yoga](https://yogalayout.com/). +TODO: Reference Yoga and Hermes/Duktape -For more information, see the introductory blog post here: [Blueprint: A JUCE Rendering Backend for React.js](https://nickwritesablog.com/blueprint-a-juce-rendering-backend-for-react-js) +React-JUCE is a hybrid JavaScript/C++ framework that enables a [React.js](https://reactjs.org/) UI for a [JUCE](http://juce.com/) application or plugin. -## Status +For more information, see the introductory blog post here: [A JUCE Rendering Backend for React.js](https://nickwritesablog.com/blueprint-a-juce-rendering-backend-for-react-js) + +## So you wanna use JavaScript to build audio apps/plugins ... + +Wait! Have you seen [Elementary](https://github.com/nick-thompson/elementary)? + +Why are we pointing you at another project? + +React-JUCE and Elementary serve two slightly different purposes. +If you're looking to develop audio apps in modern functional JavaScript +then Elementary might be the project for you. React-JUCE allows you to +add a React JS UI to your JUCE C++ app. What if we told you there is also a JS +based environment for your DSP/audio code (and yes the performance is pretty darn good)? +You can write your entire plugin (UI and DSP) in JS, oh and you can hot-reload eveything too! + +[Elementary](https://github.com/nick-thompson/elementary)? -**Approaching Beta**. We hope to announce a beta release in the coming weeks, after which we will aim our focus at stability and completeness on the path -to a 1.0 release. +OK, so why React-JUCE? -**Anticipated Breaking Changes** +Well, many reasons. Maybe you have an existing library of C++ DSP/Audio code, +perhaps its a library that you've spent hard hours (OK, hard years) crafting and +you just want a rapid development workflow for your UI? React-JUCE is for you. +Perhaps you're developing embedded Linux apps and you need C++ but want to +use React/JavaScript for your UI code? React-JUCE can help. +Maybe you hate JavaScript? Wait ... You probably shouldn't be here. +Maybe you're just much more comfortable writing DSP (or code in general) in C++ +and you just want to try out React for your UI? React-JUCE is for you. -- We'll be renaming Blueprint to react-juce before beta (#34) -- ~~Updating the examples and `npm init` template to point to npm instead of the local package~~ -- ~~`ReactApplicationRoot::evaluate` and `ReactApplicationRoot::evaluateFile` (#115)~~ -- ~~Refactoring the hot reloader and decoupling the EcmascriptEngine from ReactApplicationRoot (#65)~~ +We believe React-JUCE still has lot to offer even with [Elementary](https://github.com/nick-thompson/elementary)'s existence. +So, if you've weighed up your pros and cons then jump in, we're happy to have you! + +## Status + +**Approaching Beta**. Maintenance/Development of React-JUCE has recently been +taken over from Nick Thompson (original creator) by Joshua Marler. The repository +is going through a temporary restructure but we are pushing towards a stable v1.0. +Updates will be posted once v1.0 is hit. In the meantime please direct any questions +to discussions or to our Discord channel. ## Resources - Documentation: [Docs & Getting Started](https://docs.react-juce.dev) -- Discussions: [GitHub Discussions](https://github.com/nick-thompson/react-juce/discussions) +- Discussions: [GitHub Discussions](https://github.com/JoshMarler/react-juce/discussions) - Community: [The Audio Programmer Discord Server](https://discord.gg/3H4wwVf49v) - - Join the `#blueprint` channel and say hi! + - Join the `#react-juce` channel and say hi! ## Maintainers -- [@nick-thompson](https://github.com/nick-thompson) +Originally authored by @nick-thompson, now maintained by @JoshMarler. + - [@joshmarler](https://github.com/JoshMarler) +- [@nick-thompson](https://github.com/nick-thompson) ## Examples -React-JUCE is a young project, but already it provides the framework on which the entire user interface for [Creative Intent's Remnant](https://www.creativeintent.co/product/remnant) plugin is built. +You can check out a selection of example plugins over at [react-juce-examples](https://github.com/JoshMarler/react-juce-examples) -![Creative Intent Remnant: Screenshot](https://github.com/nick-thompson/react-juce/blob/master/RemnantScreenShot.jpg) +To see a real world example of a plugin build with react-juce checkout [Creative Intent's Remnant](https://www.creativeintent.co/product/remnant). -Besides that, you can check out the example code in the `examples/` directory. See the "Documentation" section -below for building and running the demo plugin. If you have a project written with React-JUCE that you want to share, get in touch! I would -love to showcase your work. +If you have a project written with React-JUCE that you want to share, get in touch! We would love to showcase your work. ## Contributing -See [CONTRIBUTING.md](https://github.com/nick-thompson/react-juce/blob/master/CONTRIBUTING.md) +See [CONTRIBUTING.md](https://github.com/JoshMarler/react-juce/blob/master/CONTRIBUTING.md) ## License -See [LICENSE.md](https://github.com/nick-thompson/react-juce/blob/master/LICENSE.md) +See [LICENSE.md](https://github.com/JoshMarler/react-juce/blob/master/LICENSE.md) diff --git a/docs/README.md b/docs/README.md index 0084c69d..ce153f6d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,27 +1,29 @@ # Introduction -React-JUCE is a hybrid JavaScript/C++ framework that enables a [React.js](https://reactjs.org/) frontend for a [JUCE](http://juce.com/) application or plugin. It provides an embedded, ECMAScript-compliant JavaScript engine via [Duktape](http://duktape.org/), native hooks for rendering the React component tree via `juce::Component` instances, and a flexbox layout engine via [Yoga](https://yogalayout.com/). +React-JUCE is a hybrid JavaScript/C++ framework that enables a +[React.js](https://reactjs.org/) frontend for a [JUCE](http://juce.com/) +application or plugin. -For more information, see the introductory blog post here: [React-JUCE: A JUCE Rendering Backend for React.js](https://nickwritesablog.com/blueprint-a-juce-rendering-backend-for-react-js) +For more information, see the introductory blog post here: +[React-JUCE: A JUCE Rendering Backend for React.js](https://nickwritesablog.com/blueprint-a-juce-rendering-backend-for-react-js) ## Examples -React-JUCE is a young project, but already it provides the framework on which the entire user interface for [Creative Intent's Remnant](https://www.creativeintent.co/product/remnant) plugin is built. +React-JUCE is a young project, but already it provides the framework on which +the entire user interface for [Creative Intent's Remnant](https://www.creativeintent.co/product/remnant) plugin is built. ![Creative Intent Remnant: Screenshot](_media/RemnantScreenShot.jpg) -Besides that, you can check out the example code in the `examples/` directory. See the "Documentation" section -below for building and running the demo plugin. If you have a project written with React-JUCE that you want to share, get in touch! I would -love to showcase your work. +Besides that, you can check out a selection of example plugins over at [react-juce-examples](https://github.com/JoshMarler/react-juce-examples) -## Contributing +If you have a project written with React-JUCE that you want to share, get in touch! We would love to showcase your work. -Yes, please! I would be very happy to welcome your involvement. Take a look at the [open issues](https://github.com/nick-thompson/react-juce/issues) -or the [project tracker](https://github.com/nick-thompson/react-juce/projects/1) to see if there's outstanding work that you might -be able to get started. Or feel free to propose an idea or offer feedback by [opening an issue](https://github.com/nick-thompson/react-juce/issues/new) as well. +## Contributing -I don't have a formal style guide at the moment, so please try to match the present formatting in any code contributions. +Yes, please! We would be very happy to welcome your involvement. Take a look at the [open issues](https://github.com/JoshMarler/react-juce/issues) +or the [project tracker](https://github.com/JoshMarler/react-juce/projects/1) to see if there's outstanding work that you might +be able to get started. Or feel free to propose an idea or offer feedback by [opening an issue](https://github.com/JoshMarler/react-juce/issues/new) as well. ## License -See [LICENSE.md](https://github.com/nick-thompson/react-juce/blob/master/LICENSE.md) +See [LICENSE.md](https://github.com/JoshMarler/react-juce/blob/master/LICENSE.md) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 3bbd8418..4f8cd1ac 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -3,8 +3,7 @@ ## Guides - [Getting Started](guides/Getting_Started.md) -- [Running the Examples](guides/Running_the_Examples.md) -- [Integrating Your Project](guides/Integrating_Your_Project.md) +- [Setting Up Your Project](guides/Integrating_Your_Project.md) - [Debugging with Duktape](guides/Debugging_With_Duktape.md) - [Why Not React Native?](guides/Why_Not_React_Native.md) @@ -23,11 +22,11 @@ ## Native +- [JS/C++ Interop](native/Interop.md) - [Custom Native Components](native/Custom_Native_Components.md) -- [JS/Native Interop](native/Interop.md) ## Have a Question? -- [GitHub Discussions](https://github.com/nick-thompson/react-juce/discussions) +- [GitHub Discussions](https://github.com/JoshMarler/react-juce/discussions) - [Discord Chatroom](https://discord.gg/3H4wwVf49v) -- [Open an Issue](https://github.com/nick-thompson/react-juce/issues) +- [Open an Issue](https://github.com/JoshMarler/react-juce/issues) diff --git a/docs/components/Image.md b/docs/components/Image.md index 0bba698e..c51940b9 100644 --- a/docs/components/Image.md +++ b/docs/components/Image.md @@ -19,7 +19,7 @@ import logoDataUri from "./logo.jpg"; function App(props) { return ( console.log("Mouse event!", e)}> - + ); @@ -47,7 +47,7 @@ const styles = { #### source -The image source (either a remote URL ([#14](https://github.com/nick-thompson/react-juce/issues/14)), a local file resource, or a data uri). +The image source (either a remote URL ([#14](https://github.com/JoshMarler/react-juce/issues/14)), a local file resource, or a data uri). | Type | Required | Supported | | ------ | -------- | -------------------------------------------------------------------------- | diff --git a/docs/components/Styles.md b/docs/components/Styles.md index 066d8d66..17993c1d 100644 --- a/docs/components/Styles.md +++ b/docs/components/Styles.md @@ -58,22 +58,22 @@ any other prop. In the future, we may adopt an API closer to that of React Nativ ## View Props -| Property | Support | Spec | -| -------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | -| border-left-width | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-width) | -| border-right-width | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-width) | -| border-top-width | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-width) | -| border-bottom-width | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-width) | -| border-left-color | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-color) | -| border-right-color | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-color) | -| border-top-color | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-color) | -| border-bottom-color | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-color) | -| border-bottom-left-radius | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) | -| border-bottom-right-radius | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) | -| border-top-left-radius | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) | -| border-top-right-radius | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) | -| border-width | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-width) | -| border-color | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-color) | -| border-radius | Planned [(#143)](https://github.com/nick-thompson/react-juce/issues/143) | [MDN border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) | -| background-color | Partial [(#84)](https://github.com/nick-thompson/react-juce/issues/84) | [MDN background-color](https://developer.mozilla.org/en-US/docs/Web/CSS/background-color) | -| opacity | Yes | [juce::Component::setAlpha](https://docs.juce.com/master/classComponent.html#a1b9329a87c71ed01319071e0fedac128) | +| Property | Support | Spec | +| -------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| border-left-width | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-width) | +| border-right-width | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-width) | +| border-top-width | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-width) | +| border-bottom-width | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-width) | +| border-left-color | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-color) | +| border-right-color | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-color) | +| border-top-color | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-color) | +| border-bottom-color | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-color) | +| border-bottom-left-radius | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) | +| border-bottom-right-radius | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) | +| border-top-left-radius | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) | +| border-top-right-radius | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) | +| border-width | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-width](https://developer.mozilla.org/en-US/docs/Web/CSS/border-width) | +| border-color | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-color](https://developer.mozilla.org/en-US/docs/Web/CSS/border-color) | +| border-radius | Planned [(#143)](https://github.com/JoshMarler/react-juce/issues/143) | [MDN border-radius](https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius) | +| background-color | Partial [(#84)](https://github.com/JoshMarler/react-juce/issues/84) | [MDN background-color](https://developer.mozilla.org/en-US/docs/Web/CSS/background-color) | +| opacity | Yes | [juce::Component::setAlpha](https://docs.juce.com/master/classComponent.html#a1b9329a87c71ed01319071e0fedac128) | diff --git a/docs/components/Text.md b/docs/components/Text.md index 21ddf4df..3e7491fc 100644 --- a/docs/components/Text.md +++ b/docs/components/Text.md @@ -2,7 +2,7 @@ A React component for displaying text. -Unlike React Native and React-DOM, `Text` does not yet support nesting ([#6](https://github.com/nick-thompson/react-juce/issues/6)), though +Unlike React Native and React-DOM, `Text` does not yet support nesting ([#6](https://github.com/JoshMarler/react-juce/issues/6)), though it does happily support styling, and touch handling. ## Example diff --git a/docs/components/TextInput.md b/docs/components/TextInput.md index 1c872fc1..8dc08dac 100644 --- a/docs/components/TextInput.md +++ b/docs/components/TextInput.md @@ -62,4 +62,4 @@ export default App; ## Props -**TODO**: Document props. See [the class](https://github.com/nick-thompson/react-juce/blob/master/packages/react-juce/src/components/TextInput.tsx#L11) for props in the meantime. +**TODO**: Document props. See [the class](https://github.com/JoshMarler/react-juce/blob/master/packages/react-juce/src/components/TextInput.tsx#L11) for props in the meantime. diff --git a/docs/guides/Debugging_With_Duktape.md b/docs/guides/Debugging_With_Duktape.md index 464ff1ef..ccdaf1bd 100644 --- a/docs/guides/Debugging_With_Duktape.md +++ b/docs/guides/Debugging_With_Duktape.md @@ -1,4 +1,4 @@ -# Debugger Support +#Debugger Support (Because console.log() isn't always enough) diff --git a/docs/guides/Getting_Started.md b/docs/guides/Getting_Started.md index 44c7824b..0e994e05 100644 --- a/docs/guides/Getting_Started.md +++ b/docs/guides/Getting_Started.md @@ -1,6 +1,8 @@ # Getting Started -This guide assumes you have some familiarity with [React.js](https://reactjs.org/) and with [JUCE](https://juce.com/), and it is therefore recommended that you spend some time getting comfortable there, if you're not already, before embarking on this guide. +This guide assumes you have some familiarity with [React.js](https://reactjs.org/) +and with [JUCE](https://juce.com/), and it is therefore recommended that you spend +some time getting comfortable there, if you're not already, before embarking on this guide. ## Dependencies @@ -8,29 +10,33 @@ To get started with React-JUCE, you'll first need to install a few dependencies: - [Node.js](https://nodejs.org/en/) v8.11.0+ - [npm](https://www.npmjs.com/) v5.6.0+ -- [JUCE](https://juce.com/) v5.4.2+ (Optional if you are only running the examples) - Xcode10.2+ (MacOS) - Visual Studio 2017+ (Windows) Once you have the dependencies installed, we need to clone the React-JUCE repository -itself. React-JUCE's git repository contains necessary submodules, so we'll need to -collect those as well, which we can do one of two ways: +itself. React-JUCE's git repository contains necessary submodules, so we'll need +to collect those as well, which we can do one of two ways: ```bash -$ git clone --recurse-submodules git@github.com:nick-thompson/react-juce.git +$ git clone --recurse-submodules git@github.com:JoshMarler/react-juce.git ``` or ```bash -$ git clone git@github.com:nick-thompson/react-juce.git +$ git clone git@github.com:JoshMarler/react-juce.git $ cd react-juce $ git submodule update --init --recursive ``` Note that the `git@github.com` prefix here indicates cloning via SSH. If you prefer -to work with git via HTTPS you'll want to swap in `https://github.com/nick-thompson/react-juce.git` +to work with git via HTTPS you'll want to swap in `https://github.com/JoshMarler/react-juce.git` in the above commands. -At this point, we've got everything ready to get our project up and running. Let's -move on to the next step, [running the demo plugin](Running_the_Examples.md). +At this point, we've got everything ready to get our project up and running. + +Lets take a look at running one of the example apps first: + +[Running The Examples](Running_The_Examples.md) + +If you prefer to get straight to integrating React JUCE into your project take a look [here](Integrating_Your_Project.md) diff --git a/docs/guides/Integrating_Your_Project.md b/docs/guides/Integrating_Your_Project.md index 99b3eef2..932ed44d 100644 --- a/docs/guides/Integrating_Your_Project.md +++ b/docs/guides/Integrating_Your_Project.md @@ -3,24 +3,38 @@ This step assumes you've already reviewed the [Getting Started](Getting_Started.md) guide. If not, please start there! -Ok, so you're ready to add some React.js to your JUCE project. Whether that's a totally new project or a preexisting project, getting React-JUCE involved is the same. If you're starting your project from scratch, I recommend running through the [Getting started with the Projucer](https://docs.juce.com/master/tutorial_new_projucer_project.html) tutorial on the JUCE website, if you haven't already. +Ok, so you're ready to add some React.js to your JUCE project. Whether that's a totally new project or a preexisting project, adding React-JUCE requires the same steps. +If you're starting your project from scratch, we recommend running through the [Getting started with the Projucer](https://docs.juce.com/master/tutorial_new_projucer_project.html) +tutorial on the JUCE website, if you haven't already. -Now before we write any code, we have to add React-JUCE to our JUCE project. Fortunately, JUCE makes this super -easy with the JUCE module format, and React-JUCE abides by that format. Follow along with the [Manage JUCE modules](https://docs.juce.com/master/tutorial_manage_projucer_project.html#tutorial_manage_projucer_project_managing_modules) section of the Projucer tutorial, wherein you'll need to add the React-JUCE module by pointing the Projucer to its location on disk. The actual React-JUCE JUCE module is located in the `react_juce` subdirectory of the root of the React-JUCE project. +Now before we write any code, we have to add React-JUCE to our JUCE project. +We can do this in one of two ways, using the Projucer or using CMake. -## Template Generator +## Adding React-JUCE using CMake + + TODO: Complete instructions + +## Adding React-JUCE using the Projucer + + TODO: Complete instructions + + Follow along with the [Manage JUCE modules](https://docs.juce.com/master/tutorial_manage_projucer_project.html#tutorial_manage_projucer_project_managing_modules) section of the Projucer tutorial, wherein you'll need to add the React-JUCE module by pointing the Projucer to its location on disk. The actual React-JUCE JUCE module is located in the `react_juce` subdirectory of the root of the React-JUCE project. + +## Setting up your JS/React code using the Template Generator Next, the first thing we want to do here is write some React.js, so let's start with a "Hello World!" of our own. React-JUCE's `react-juce` npm package carries a template generator that you can use to boostrap a React application for your project. For this step, let's assume your JUCE project directory is at `~/MyProject`, the source files are at `~/MyProject/Source`, and we want to put the React application source at `~/MyProject/Source/jsui` (note, you can put this wherever you want). Now, to use the template generator, we start again at the root of the React-JUCE git repository: ```bash -$ pwd -/Users/nick/Dev/react-juce +$ cd ~/ $ cd packages/react-juce $ npm run init -- ~/MyProject/Source/jsui ``` -The template generator will create the `jsui` directory as suggested in the example command above, fill it -with a basic "Hello World!" app, and install local dependencies like React.js and Webpack. Like the [[GainPlugin Example|running-the-example]], we now need to build our output bundle. +The template generator will create the `jsui` directory as suggested in the +example command above, fill it with a basic "Hello World!" app, and install +local dependencies like React.js and Webpack. +Like the [[GainPlugin Example|running-the-example]], we now need to build our +output bundle. ```bash $ cd ~/MyProject/Source/jsui @@ -30,9 +44,17 @@ $ npm start At this point we've got our app bundle ready to roll, so let's turn over to the native side to mount this into our JUCE project. -## Native Code +## Choosing your JavaScript Engine + +TODO: Add section on Hermes versus Duktape + +## Setting up your native C++/JUCE code -Because we've already added the React-JUCE module to our Projucer project, we can jump straight into the code on the native side. Part of the native React-JUCE API is a particularly important class called `reactjuce::ReactApplicationRoot`. This class is mostly just a `juce::Component`, and in that way you should think about using it the same way you might use a `juce::Slider` in your application. +Because we've already added the React-JUCE module to our Projucer project, we +can jump straight into the code on the native side. Part of the native React-JUCE +API is a particularly important class called `reactjuce::ReactApplicationRoot`. +This class is mostly just a `juce::Component`, and in that way you should think +about using it the same way you might use a `juce::Slider` in your application. For example, let's suppose that we have our `MainComponent` or our `AudioProcessorPluginEditor` at the top of our project: diff --git a/docs/guides/Running_the_Examples.md b/docs/guides/Running_the_Examples.md deleted file mode 100644 index 754fbad2..00000000 --- a/docs/guides/Running_the_Examples.md +++ /dev/null @@ -1,70 +0,0 @@ -# Running the GainPlugin Example project - -This step assumes you've already reviewed the [Getting Started](Getting_Started.md) guide. If not, -please start there! - -## GainPlugin - -![Gain Plugin example project user interface](../_media/gainplugin.jpg) - -React-JUCE includes an extremely simple utility gain plugin to demonstrate the minimal -code required for integrating React-JUCE into a JUCE project. To get it running, -we only need two steps: compiling the JavaScript bundle, and then compiling and -running the native code. - -### JavaScript Bundle - -All React-JUCE projects have two components: we have the native code that knows how -to mount the React application into our JUCE project and satisfy calls from React's -reconciler, and then we have the React.js application code that we want to run in the -native environment. In order to ease this handoff, we're using a tool in this -example called [Webpack](https://webpack.js.org/) that can compile a complete JavaScript project into a single -file. That single file is then the only thing we need to execute in the native -environment. - -To get the GainPlugin up and running for the first time, we have to first perform -that compilation step. So, from the root of the `React-JUCE` git repository: - -```bash -$ cd examples/GainPlugin/Source/jsui/ -``` - -The `jsui/` directory here is the top level directory of all the -React.js application code that we used to build the example interface. -We use a build step managed by npm to compile all of our application javascript -into a single file that can be easily loaded up in the native app: - -```bash -$ npm install -$ npm run build -``` - -At this point, you'll see an output file in `examples/GainPlugin/Source/jsui/build/js/`. That file location is important, because that's where the native code looks for executing the output file. - -### Native - -Now that we have our JavaScript bundle, the last step is simple: just hit Build and -Run from your IDE! When the JUCE PluginEditor gets initialized, it will find your -JavaScript build and evaluate it within the embedded interpreter to draw the -GainPlugin interface. - -## Hot Reloading - -The GainPlugin example is preconfigured with hot reloading, so that as you edit -the React application code, your interface will redraw itself instantly. In order -to take advantage of this, we need to recompile our JavaScript bundle on the -fly as we're editing our code. Fortunately, Webpack makes that simple, so from -within the `jsui/` directory: - -```bash -$ npm start -``` - -This will first build your JavaScript bundle, then wait and watch your source files -for changes. When it finds a change, it will pick that change up and incrementally -rebuild your bundle. In turn, React-JUCE will pick up the change to the bundle file -and redraw your interface. - -Now that you're up and running, take a minute to tweak the GainPlugin React -application to get a sense of the workflow! When you're done, let's move on to -the next step, [adding React-JUCE to your own project](New_Project.md).