React Three Fiber is a great set of tools for making immersive marketing and creative content using JavaScript, three.js, and React, but the standard templates make only independent web apps. Instead, what we wanted was to integrate the 3D experience into an existing marketing site based on WordPress for our homepage. Here’s how you can also deploy your R3F project integrated with your WordPress site and, optionally, configure automated continuous deploys from your GitHub repo to your WordPress site.

The Wrong Way: Should I just use an iframe?

The simplest method would be to deploy your R3F app as its own website and then make a WordPress page that is nothing but an iframe pulling in the other site. The major downside to this approach is in SEO – search engines won’t consider that content as a part of your site, so this page in your WordPress won’t rank in search results for the content in the iframe. For a marketing site, that’s a deal-breaker.

The Right Way: Using the ReactPress WordPress plugin

ReactPress is a WordPress plugin that helps integrate React apps directly into pages, but the instructions require that you run an entire local development copy of your WordPress site. As JS developers, that sounded like a lot of time and effort to get setup, so We’ll show you our easier setup instead and also share tips for styling full-page 3D content.

Combine the flexibility of WordPress with the UI capabilities of React and seamlessly integrate create-react-app into your WordPress project for your next SaaS.

https://wordpress.org/plugins/reactpress/

Step 1: Create React App

For this step, just the standard setup for a React Three Fiber project. Here’s the starter code from their docs:

# Create app
npx create-react-app my-app
cd my-app

# Install dependencies
npm install three @react-three/fiber

# Start
npm run start

While Create React App isn’t strictly required, it will make it easier later for us to configure the correct file paths for building.

Step 2: Make your React Three Fiber app

Next, Add this full-page CSS to the auto-generated index.css and then develop your R3F app as usual or maybe copy one from their examples.

html, body, #root {
  width: 100%;
  height: 100%;
  margin: 0;
  padding: 0;
}

Step 3: Setup ReactPress

Install and activate the ReactPress plugin from your WordPress admin panel. Next, use the new ReactPress entry at the top-level of your admin navigation bar to visit the ReactPress admin settings. This will give a folder path that provides two important pieces of information: the path to the folder where your built react app needs to be uploaded and the public path to configure our React build to use. Take note of this path for use in later steps.

Screenshot of the ReactPress Admin screen. It shows a message about where to upload react apps with folder path.
ReactPress screenshot https://rockiger.com/en/reactpress/getting-started/

Step 4: Configure React build

We need to configure the React app build to use the URL path structure that will match where the files are hosted on your WordPress, this is the commonly called the public path or public url. In your package.json, find the build script and edit it to set a PUBLIC_URL environment variable. The pattern for the path comes from the path step 3, /wp-content/reactpress/apps/ plus an app name and /build.

  "scripts": {
    "start": "react-scripts start",
    "build": "PUBLIC_URL=/wp-content/reactpress/apps/my-app-name/build react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  }

Note: if you’re using Windows and not using Git Bash, you’ll also need to add cross-env in order for the PUBLIC_URL setting to work. The above should work as-is for Linux and MacOS.

Step 5: First deploy

For the first deploy, we’ll manually upload the files via FTP. Later, we’ll setup automated deploys for updates.

  1. Run npm run build in your react app to create a production build.
  2. Connect to your server over FTP and use the file path noted from step 3 to locate the reactpress/apps folder.
  3. In this folder, create a new folder with the same app name you used in step 4.
  4. Transfer the build folder from your local project to the server inside the folder you just created.

Step 6: ReactPress configuration

Return to the ReactPress admin page from Step 3 or refresh the page if you still have it open. It should now detect your uploaded app. Follow the instructions listed to create a WordPress page that will host your R3F app.

Screenshot of ReactPress app setup
ReactPress screenshot https://rockiger.com/en/reactpress/getting-started/

Step 7: Integrate with your WordPress theme

Visit the URL you selected for your page in step 6 and you will find your live app… well kind of. You’ll probably find the canvas doesn’t fill the page among other styling issues. This is the disadvantage of not doing the local WordPress development environment as suggested by ReactPress. Not to worry though, you’re just a few tweaks away from a complete project.

Screenshot of the Immers Home 3D scene scrunched up in half of the available screen space with large whitespace below.
This doesn’t look right…

You can use browser developer tools on your live site to diagnose the issues and test solutions, or you can pretty faithfully reproduce the theme context in your local React project by copying all the stylesheet <link> tags and <style> blocks from your live page’s head into your project’s public/index.html (depending on your theme you may also need to reproduce the page hierarchy around your #root, but we didn’t). Here are some of the key changes we made in this stage:

  • Update the full-page style selector from Step 3 to also select any parent containers of your #root in the live page, e.g. html, body, #page-container, #et-main-area, #root
  • If you’re using ScrollControls, avoid double-scrollbars by adding rule to hide the page footer (or adjust your full-page styles to leave room for it)
  • Increase the specificity of selectors you’ve added to index.css by prefixing them with #root to ensure they take precedence over theme settings

At this point, you can deploy again via FTP and call it a day, if you’re really confident that you’re finished. If, more realistically, you expect there might be a few rounds of revisions, continue on to learn how to setup continuous deploys from GitHub to save you some time on deploys.

Step 8: Automated deploys with GitHub Actions

It’s so convenient to be able to just merge the code and have it deploy automatically rather than logging into your server and hoping you don’t accidentally break the entire site. For this we’re going to use FTP-Deploy-Action from GitHub user SamKirkland. You should first create a new FTP user with limited access. This will avoid any catastrophes by making sure the CI cannot delete any files outside of the React app folder. Set the user’s FTP folder to be the app name folder within reactpress/apps/ that you created on the server in step 5.

You might need to log back into FTP with the previous user and delete the build folder if the new user cannot access it

Next, add this worklow to your repo as .github/workflows/deploy.yml and update the server and username fields.

name: Build & deploy

on:
  push:
    branches:
      - main

jobs:
  deploy:
    name: deploy
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v3
    
    - name: Install Node.js
      uses: actions/setup-node@v3
      with:
        node-version: 16
    
    - name: Install NPM packages
      run: npm ci
    
    - name: Build project
      run: npm run build
    
    - name: Deploy to wordpress
      uses: SamKirkland/FTP-Deploy-Action@4.3.3
      with:
        server: yourdomain.com
        username: username@yourdomain.com
        password: ${{ secrets.ftp_password }}
        local-dir: ./build/
        server-dir: ./build/

Finally, visit your GitHub repo’s Settings -> Security -> Secrets and variables -> Actions page and click “New repository secret” to add the ftp_password secret with the password you created for the new user. Now, push this into your main branch and all future changes will be automatically deployed to your WordPress!

Thanks for reading this React Three Fiber guide from Immers Space. If you found it useful, please sign up for our mailing list below to be notified of future guides. Questions or issues? Comment below. If you’d like help creating your immersive web experience, hire us!