Gutenberg Mobile

https://github.com/wordpress-mobile/gutenberg-mobile
Admin
Gutenberg Mobile is the mobile version of the WordPress Gutenberg project, built for Android and iOS...
Tokens:11,719
Snippets:39
Trust Score:9.1
License:GPL-2.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start Metro Server for Gutenberg Mobile

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/WPiOS Integration.md

Starts the Metro bundler server within the gutenberg-mobile project with a reset cache. This ensures that the latest JavaScript code changes are picked up by the WPiOS application.

```sh
npm run start:reset
```

--------------------------------

### Local Gutenberg Mobile Checkout Setup

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/WPAndroid Integration.md

Instructions for setting up WordPress Android to use a local checkout of the Gutenberg Mobile project. This involves copying a Gradle configuration file, updating a path variable, and running the Metro server.

```bash
npm install
npm ci
npm run start:reset
```

```gradle
# Copy local-builds.gradle-example to local-builds.gradle
# Update localGutenbergMobilePath in local-builds.gradle to your local gutenberg-mobile checkout path
// Example of dependency substitution in settings.gradle:
// if (new File("../local-builds.gradle").exists()) {
//     apply from: "../local-builds.gradle"
// }

// Example of how the dependency might be substituted:
implementation "$rootProject.gradle.ext.gutenbergMobileBinaryPath:$rootProject.ext.gutenbergMobileVersion"
```

--------------------------------

### Install Pods with Local Gutenberg Checkout

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/WPiOS Integration.md

Installs CocoaPods dependencies for WordPress-iOS using a local checkout of the gutenberg-mobile project. This command sets the LOCAL_GUTENBERG environment variable to true, directing the build process to use the local gutenberg-mobile bundle.

```sh
LOCAL_GUTENBERG=true bundle exec pod install
```

--------------------------------

### Setup E2E Test Environment

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Initializes and prepares the environment required for running end-to-end (E2E) tests. This command ensures all necessary dependencies and configurations are in place before executing E2E test suites.

```shell
npm run core test:e2e:setup
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Installs the required Node.js version using nvm and then installs all project dependencies using npm. This step is crucial before running the application.

```shell
nvm install && npm install
```

--------------------------------

### Create Gutenberg Mobile Bundles

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/WPiOS Integration.md

Generates JavaScript bundles for the gutenberg-mobile project. This command is used when preparing to share a WPiOS installable build that includes updated gutenberg-mobile code.

```sh
npm run bundle
```

--------------------------------

### Deploying react-native-bridge from CI

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/WPAndroid Integration.md

Details on how new versions of react-native-bridge are deployed via CI. This includes the commands executed during the CI process and the versioning scheme based on commits or tags.

```bash
npm ci
npm run bundle:android
gutenberg/packages/react-native-bridge/android/publish-aztec-and-bridge.sh <version>
```

--------------------------------

### Install Pods with Custom Local Gutenberg Path

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/WPiOS Integration.md

Installs CocoaPods dependencies for WordPress-iOS, specifying a custom relative path to the local gutenberg-mobile checkout. This is used when gutenberg-mobile is not located in the default '../gutenberg-mobile' directory.

```sh
LOCAL_GUTENBERG=../../xyz/gutenberg-mobile bundle exec pod install
```

--------------------------------

### Add Aztec iOS Dependency

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/WPiOS Integration.md

Specifies how to add the WordPress-Aztec-iOS library from a Git repository to your project's Podfile, allowing for specific commit tracking.

```ruby
pod 'WordPress-Aztec-iOS', git: 'https://github.com/wordpress-mobile/WordPress-Aztec-iOS.git', commit: ''
```

--------------------------------

### Update WPiOS Podfile for PR Testing

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/WPiOS Integration.md

Installs CocoaPods dependencies after modifying the WPiOS Podfile to point to a specific gutenberg-mobile commit. This step is crucial for integrating PR changes into the WPiOS build.

```sh
bundle exec pod install
```

--------------------------------

### Run Gutenberg Mobile App

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Starts the Metro bundler for development and then compiles and runs the application on Android or iOS. The packager serves the app bundle to the clients.

```shell
npm run start:reset
```

```shell
npm run core android
```

```shell
npm run core ios
```

--------------------------------

### Shell Command for Building Native Packages

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

An example of a shell command used to build a native package, specifically the VideoPress package. This command is often necessary to extract strings used only in the native version before internationalization updates.

```shell
./bin/run-jetpack-command.sh "-C projects/packages/videopress build"
```

--------------------------------

### Locale Setup Configuration

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Defines the structure for passing locale information during editor initialization. This includes the plugin domain and a callback function for retrieving translations, essential for internationalizing the mobile editor.

```javascript
[
  {
    "domain": "<DOMAIN / PLUGIN NAME>", 
    "getTranslation": "<CALLBACK_FOR_GETTING_TRANSLATION>"
  },
  ...
]
```

--------------------------------

### Updating WPAndroid Binary Version

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/WPAndroid Integration.md

Instructions for updating the `gutenbergMobileVersion` property in WordPress Android's `build.gradle` file to point to a newly deployed binary version. It also mentions the condition to comment out local paths.

```gradle
// In WordPress-Android/build.gradle
ext.gutenbergMobileVersion = "<new_version>"

// Ensure localGutenbergMobilePath in local-builds.gradle is commented out to use the binary version
```

--------------------------------

### WPAndroid Integration Configuration

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/WPAndroid Integration.md

This section details how WordPress Android integrates with Gutenberg Mobile, specifically focusing on the `react-native-bridge` dependency and the mechanism for substituting binary dependencies with local source code during development.

```APIDOC
Project: WordPress Android Integration

Dependency Management:
  - WPAndroid integrates `react-native-bridge` as a binary dependency fetched from a remote Maven repository.
  - CI pipelines in the Gutenberg Mobile repository deploy new versions upon commits to `trunk`, open PRs, or tag creation.

Local Development Setup:
  - To use a local checkout of `gutenberg-mobile` for development:
    1. Copy `local-builds.gradle-example` to `local-builds.gradle` in the WordPress-Android project.
    2. Update the `localGutenbergMobilePath` variable in `local-builds.gradle` to point to your local `gutenberg-mobile` directory.
    3. Ensure the Metro server is running (`npm run start:reset` in `gutenberg-mobile`).
  - This setup uses Gradle's dependency substitution to build `react-native-bridge` and other sublibraries from the local folder instead of the binary dependency.

Configuration Properties:
  - `ext.gutenbergMobileVersion`: Property in `WordPress-Android/build.gradle` that specifies the version of the `react-native-bridge` binary dependency.
  - `localGutenbergMobilePath`: Variable in `local-builds.gradle` that specifies the path to the local `gutenberg-mobile` checkout for development.

Build Process:
  - CI deploys versions using:
    - `npm ci`
    - `npm run bundle:android`
    - `gutenberg/packages/react-native-bridge/android/publish-aztec-and-bridge.sh <version>`
  - WPAndroid's build process can be configured to use either the binary version (by setting `ext.gutenbergMobileVersion`) or the local checkout (by configuring `local-builds.gradle`).

Testing PRs:
  - To test a Gutenberg Mobile PR in WPAndroid:
    1. Set up WPAndroid for local checkout (as described above).
    2. Switch your `gutenberg-mobile` checkout to the desired PR branch.
    3. Run the WordPress-Android application.
```

--------------------------------

### Update WPiOS Podfile for Alpha Tag

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/WPiOS Integration.md

Modifies the WPiOS config.yml file to reference a newly released alpha tag of gutenberg-mobile. This ensures that WPiOS uses the alpha version for testing.

```config
tag: v1.51.0-alpha2
```

--------------------------------

### Run Unit Tests with Debugger

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Starts the unit test suite with debugger support enabled. This allows developers to attach a Chrome debugger via `chrome://inspect` to step through test execution. Developers can insert `debugger` statements in the code to set breakpoints.

```shell
npm run test:debug
```

--------------------------------

### Release Alpha Version of Gutenberg Mobile

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/WPiOS Integration.md

Tags a merge commit in gutenberg-mobile with an alpha version number, following a specific naming convention (e.g., v1.51.0-alpha1). This is part of the process to release an alpha version for WPiOS to use.

```sh
git tag v1.51.0-alpha1
```

--------------------------------

### Test Gutenberg Mobile PR in WPiOS

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/WPiOS Integration.md

Updates the WPiOS Podfile to reference a specific commit hash from a gutenberg-mobile pull request. This allows testing of unmerged changes from gutenberg-mobile within the WPiOS application.

```config
commit: 123456789
```

--------------------------------

### Uncomment Aztec iOS Podfile Line

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/WPiOS Integration.md

Uncomments a specific line within the ios-xcframework/Podfile in the gutenberg-mobile repository. This action is a prerequisite for testing changes to the Aztec Editor iOS codebase within WPiOS.

```config
# pod 'AztecEditor-iOS', :path => '../AztecEditor-iOS'
```

--------------------------------

### Appium Server Configuration and Capabilities

Source: https://github.com/wordpress-mobile/gutenberg-mobile/wiki/Getting-started-with-UI-tests

Details on configuring the Appium server and its WebDriver capabilities for connecting to simulators or devices. This includes specifying the platform version and the application path.

```APIDOC
Appium Server:
  Default Port: 4723
  Configuration File: __device-tests__/helpers/serverConfigs.js
  Output Log: appium-out.log

WebDriver Capabilities:
  These capabilities are used to connect Appium to a simulator or device.
  Configuration Location: __device-tests__/helpers/caps.js

  Key Capabilities:
  - platformVersion: The version of the operating system on the target device or simulator.
    Example: "9.0" for Android, "12.2" for iOS.
    Note: This value is upper-bounded by CI limits but can be adjusted locally.
  - app: The path to the application file.
    Can be an absolute path to a .app or .apk file.
    Can also be a path relative to the Appium root directory.
    Example: "path/to/your/app.apk"

  Full Capability Specification: http://appium.io/docs/en/writing-running-appium/caps/
```

--------------------------------

### Run E2E Tests Locally

Source: https://github.com/wordpress-mobile/gutenberg-mobile/wiki/Getting-started-with-UI-tests

Commands to execute end-to-end tests on iOS and Android simulators/devices locally. Ensure Metro is not running before executing these commands to avoid conflicts.

```Shell
yarn test:e2e:ios:local
```

```Shell
yarn test:e2e:android:local
```

--------------------------------

### VSCode Recommended Extensions

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Information about recommended Visual Studio Code extensions for developing the Gutenberg Mobile project, such as React Native Tools, which aids in debugging and running the application.

```javascript
// Recommended VSCode Extension:
// React Native Tools (vsmobile.vscode-reactnative)
// Enables running the packager, launching the app on iOS/Android, and debugging.
```

--------------------------------

### Clone Gutenberg Mobile Project

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Clones the main repository and initializes/updates its submodules to ensure all necessary components are present for development.

```shell
git clone --recurse-submodules https://github.com/wordpress-mobile/gutenberg-mobile.git
```

```shell
git submodule init
git submodule update
```

--------------------------------

### Run ESLint for Linting

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Performs static analysis and checks code style using ESLint, based on the configuration inherited from the `gutenberg` project. This command identifies potential code quality issues and style violations.

```shell
npm run lint
```

--------------------------------

### Clean and Reinstall Dependencies

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Cleans various caches and reinstalls NPM packages from scratch. This is useful when changes to configuration files like package.json or Babel configuration do not take effect.

```shell
npm run clean:install
```

--------------------------------

### Run Gutenberg Mobile on Specific iOS Simulator

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Compiles and runs the application on a specific iOS simulator device. Use `xcrun simctl list devices` to find available simulator names.

```shell
npm run core ios --simulator="DEVICE_NAME"
```

--------------------------------

### Define UI Test Scenario (JavaScript)

Source: https://github.com/wordpress-mobile/gutenberg-mobile/wiki/Writing-a-UI-test

Adds a new test scenario using the 'it' function, specifying a descriptive string and an asynchronous callback function for test execution. This structure is fundamental for organizing individual test cases within the test suite.

```javascript
it( 'should be able to do something', async () => {
	// Code to do something...
});
```

--------------------------------

### JavaScript Integration for Plugin Translations

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Demonstrates how to import translation functions and register them for a specific plugin within the Gutenberg Mobile editor initialization. This involves defining a domain and providing a callback function to retrieve translations.

```javascript
import { getTranslation as getJetpackTranslation } from './i18n-translations/jetpack';

const pluginTranslations = [
	{
		domain: 'jetpack',
		getTranslation: getJetpackTranslation,
	},
];
```

--------------------------------

### Run Unit Tests with Jest

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Executes the project's unit test suite using the Jest test runner. These tests are designed to run on desktop environments against Node.js. The output will indicate test pass or fail status.

```shell
npm run test
```

--------------------------------

### Add React Native Mirror Repository to build.gradle

Source: https://github.com/wordpress-mobile/gutenberg-mobile/wiki/Bintray-mirror-of-React-Native

This snippet shows how to configure your Android project's build.gradle file to include the custom Maven repository hosting React Native packages for Gutenberg Mobile. This allows your project to resolve these dependencies without needing a local Node.js environment.

```gradle
maven { url "https://dl.bintray.com/wordpress-mobile/react-native-mirror/" }
```

--------------------------------

### NPM Internationalization Commands

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Provides commands for managing translation files and generating localization assets. These commands automate the process of downloading optimized translations and creating platform-specific string files.

```APIDOC
NPM Commands:

`npm run i18n:update`
  - Description: Downloads optimized translations and generates localization strings files for all plugins. This command is automatically executed before generating a bundle via the `prebundle:js` hook.
  - Related Commands: `npm run bundle`, `npm run i18n:check-cache`

`npm run i18n:check-cache`
  - Description: Downloads un-optimized translations for plugins that do not have an existing cache folder. This command is automatically executed after dependency installation via the `postinstall` hook.
  - Related Commands: `npm install`, `npm run i18n:update`
```

--------------------------------

### Run E2E Test on iOS

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Executes a specific end-to-end test file on an iOS simulator or device. The `--` argument is used to pass additional arguments to the underlying test runner, specifying the target test file.

```shell
npm run test:e2e:ios:local -- -- gutenberg-editor-media-blocks-@canary.test
```

--------------------------------

### Update Bintray Repository Script

Source: https://github.com/wordpress-mobile/gutenberg-mobile/wiki/Bintray-mirror-of-React-Native

This script is used to update the Maven mirror on Bintray with new versions of React Native or jsc-android packages. It requires checkout of the Gutenberg Mobile project, execution of the script, and provision of Bintray username and API key for uploading packages.

```shell
./bin/update-bintray-repo.sh
```

--------------------------------

### Gutenberg Mobile Block Usage Analysis

Source: https://github.com/wordpress-mobile/gutenberg-mobile/wiki/1.0-Scope

Analysis of block usage in public WordPress.com posts published via mobile apps, indicating the most common content types for the Gutenberg Mobile project.

```APIDOC
Block Usage Analysis:
  Sample size: 1578 posts
  core/paragraph: 88% (1385)
  core/image: 62% (974)
  core/heading: 13% (205)
  core/list: 8% (123)
  core/quote: 7% (115)
  core/separator: 5% (81)
  core/embed: 4% (61)
  core/table: 0% (7)
  core/preformatted: 0% (3)
  core/shortcode: 0% (1)
  core/freeform: 0% (1)

  Note: Embeds were not properly detected and need further investigation. Table, preformatted, shortcode, and freeform blocks had minimal usage in this sample.
```

--------------------------------

### iOS Bridge Delegate: replaceBlock Method

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/RELEASE-NOTES.txt

Introduces the `replaceBlock` method to the iOS bridge delegate. This method is designed to match a block using its client ID and replace its contents.

```APIDOC
iOSBridgeDelegate:
  replaceBlock(match: String, content: String)
    - Replaces a block in the editor.
    - Parameters:
      - match: A string used to identify and match the block to be replaced (e.g., clientID).
      - content: The new content or structure to replace the existing block with.
    - Related Methods: Methods for block manipulation and communication between native and JavaScript layers.
```

--------------------------------

### Run ESLint to Fix Violations

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Executes ESLint with the intention of automatically fixing identified code style violations and linting errors. This command helps maintain a consistent codebase by applying automated corrections.

```shell
npm run lint:fix
```

--------------------------------

### NPM Scripts for i18n Updates

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Configures NPM scripts for managing internationalization (i18n) tasks. These scripts facilitate checking translation caches, updating translation files, and running update tests by specifying plugin names and source paths.

```javascript
"scripts": {
  "i18n:check-cache": "... jetpack wp-plugins/jetpack",
  "i18n:update": "... jetpack wp-plugins/jetpack ./jetpack/projects/plugins/jetpack/extensions",
  "i18n:update:test": "... jetpack wp-plugins/jetpack ./jetpack/projects/plugins/jetpack/extensions"
}
```

--------------------------------

### Run E2E Test on Android (Watch Mode)

Source: https://github.com/wordpress-mobile/gutenberg-mobile/blob/trunk/README.md

Runs end-to-end tests on an Android device or emulator with watch mode enabled. Watch mode automatically re-runs tests when changes are detected in the codebase, facilitating rapid development and debugging.

```shell
npm run test:e2e:android:local -- --watch
```
Tokens:
Raw