@wordpress/react-native-editor Edit

This is the mobile version of Gutenberg, targeting Android and iOS. It’s a React Native library bootstrapped by CRNA and now ejected.

Getting Started Getting Started

Prerequisites Prerequisites

For a developer experience closer to the one the project maintainers current have, make sure you have the following tools installed:

  • git
  • nvm
  • Node.js and npm (use nvm to install them)
  • AndroidStudio to be able to compile the Android version of the app
  • Xcode to be able to compile the iOS app
  • CocoaPods(sudo gem install cocoapods) needed to fetch React and third-party dependencies.

Note that the OS platform used by the maintainers is macOS but the tools and setup should be usable in other platforms too.

Top ↑

Clone the project Clone the project

  • Clone the project:
git clone https://github.com/WordPress/gutenberg.git

Top ↑

Set up Set up

Before running the demo app, you need to download and install the project dependencies. This is done via the following command:

nvm install --latest-npm
npm install

Top ↑

Run Run

npm run native start

Runs the packager (Metro) in development mode. The packager stays running to serve the app bundle to the clients that request it.

With the packager running, open another terminal window and use the following command to compile and run the Android app:

npm run native android

The app should now open in a connected device or a running emulator and fetch the JavaScript code from the running packager.

To compile and run the iOS variant of the app using the default simulator device, use:

npm run native ios

which will attempt to open your app in the iOS Simulator if you’re on a Mac and have it installed.

Top ↑

Running on Other iOS Device Simulators Running on Other iOS Device Simulators

To compile and run the app using a different device simulator, use:

npm run native ios --simulator="DEVICE_NAME"

For example, if you’d like to run in an iPhone Xs Max, try:

npm run native ios --simulator="iPhone Xs Max"

To see a list of all of your available iOS devices, use xcrun simctl list devices.

Top ↑

Troubleshooting Troubleshooting

Some times, and especially when tweaking anything in the package.json, Babel configuration (.babelrc) or the Jest configuration (jest.config.js), your changes might seem to not take effect as expected. On those times, you might need to clean various caches before starting the packager. To do that, run the script: npm run native start:reset. Other times, you might want to reinstall the NPM packages from scratch and the npm run native clean:install script can be handy.

Top ↑

Developing with Visual Studio Code Developing with Visual Studio Code

Although you’re not required to use Visual Studio Code for developing gutenberg-mobile, it is the recommended IDE and we have some configuration for it.

When you first open the project in Visual Studio, you will be prompted to install some recommended extensions. This will help with some things like type checking and debugging.

Prompt to install recommended extensions

One of the extensions we are using is the React Native Tools. This allows you to run the packager from VSCode or launch the application on iOS or Android. It also adds some debug configurations so you can set breakpoints and debug the application directly from VSCode. Take a look at the extension documentation for more details.

Top ↑

Unit Tests Unit Tests

Use the following command to run the test suite:

npm run native test

It will run the jest test runner on your tests. The tests are running on the desktop against Node.js.

To run the tests with debugger support, start it with the following CLI command:

npm run native test:debug

Then, open chrome://inspect in Chrome to attach the debugger (look into the “Remote Target” section). While testing/developing, feel free to sprinkle debugger statements anywhere in the code that you’d like the debugger to break.

Top ↑

Writing and Running Unit Tests Writing and Running Unit Tests

This project is set up to use jest for tests. You can configure whatever testing strategy you like, but jest works out of the box. Create test files in directories called __tests__ or with the .test.js extension to have the files loaded by jest. See an example test here. The jest documentation is also a wonderful resource, as is the React Native testing tutorial.

Top ↑

UI Tests UI Tests

This repository uses Appium to run UI tests. The tests live in __device-tests__ and are written using Appium to run tests against simulators and real devices. To run these you’ll need to check off a few things:

  • When running the tests, you’ll need to ensure the Metro bundler (npm run native start) is not running.
  • Appium CLI installed and available globally. We also recommend using appium-doctor to ensure all of Appium’s dependencies are good to go. You don’t have to worry about starting the server yourself, the tests handle starting the server on port 4723, just be sure that the port is free or feel free to change the port number in the test file.
  • For iOS a simulator should automatically launch but for Android you’ll need to have an emulator with at least platform version 8.0 fired up and running.

Then, to run the UI tests on iOS:

npm run native test:e2e:ios:local

and for Android:

npm run native test:e2e:android:local

To run a single test instead of the entire suite, use npm run native device-tests:local. Here’s an example that runs only gutenberg-editor-paragraph.test:

TEST_RN_PLATFORM=ios npm run native device-tests:local gutenberg-editor-paragraph.test

Note: You might experience problems that seem to be related to the tests starting the Appium server, e.g. errors that say Connection Refused, Connection Reset or The requested environment is not available. For now, you can manually start the Appium server via appium desktop or the CLI, then change the port number in the tests while (optionally) commenting out related code in the beforeAll and afterAll block.

For a more detailed outline of the UI tests and how to get started writing one, please visit the UI Test documentation and our contributing guide.

You might want to use Visual Studio Code as an editor. The project includes the configuration needed to use the above codestyle and linting tools automatically.

Top ↑

License License

Gutenberg Mobile is an Open Source project covered by the GNU General Public License version 2.