New React 360 GitLab VR Framework

A panoramic photograph can show someone a place. An interactive VR interface can help them explore it: turn toward a point of interest, select a label, and reveal the information that matters. For a software team, the challenge is making that experience both engaging for visitors and maintainable for developers.

In 2019, React 360 offers a useful starting point for browser-based immersive interfaces, especially when a team already knows React. GitLab provides the repository, review process, and automation needed to develop those interfaces collaboratively.

This guide reflects the 2019 development environment; tools, browser support, and interfaces may have changed since then.

First, an important clarification: “React 360 GitLab VR Framework” is not the name of a separate, official framework. React 360 is the immersive application framework; GitLab is the platform you can use to manage and deliver a React 360 project. Their value comes from a practical development workflow, not a special integration that automatically makes VR applications work everywhere.

What React 360 Brings to VR Development

React 360, the successor to React VR, lets developers build interactive experiences using JavaScript and React components. It is particularly suited to placing user interfaces within immersive environments, including scenes built around 360-degree photographs.

Rather than treating every interface element as a custom 3D object, React 360 supports familiar layout concepts through components such as View and Text. Those interfaces can be rendered onto surfaces positioned within a scene.

That makes it a reasonable option for:

• Virtual tours with information panels.
• Product demonstrations with selectable details.
• Training environments built around panoramic imagery.
• Immersive editorial or educational presentations.

It is not a shortcut to building a high-performance, physics-heavy VR game. A dedicated game engine may be a better choice when the core requirements are complex simulation, sophisticated controller interactions, or extensive real-time 3D rendering.

Browser access does not guarantee identical behavior

A React 360 experience can be explored through a conventional browser interface, with immersive headset behavior dependent on the browser, device, and available VR support.

In 2019, browser VR capabilities are still uneven. Desktop viewing, touch interaction, and headset viewing should be treated as distinct test targets. A successful desktop preview does not establish that a scene is comfortable or functional inside a headset.

What GitLab Adds

GitLab does not render a VR scene or translate an application into every headset’s native format. It supports the engineering work around the application:

• Version control: track changes to components, configuration, and assets.
• Merge requests: review code and discuss interaction changes before merging.
• Issue tracking: record defects, requirements, and device-specific problems.
• CI/CD: install dependencies, build the application, and publish approved output.
• Static hosting: use GitLab Pages when the application can be served as static files.

These capabilities are useful for VR because a small change can affect more than appearance. Moving a panel can alter readability; increasing image resolution can slow loading; changing an input handler can break interaction on another device.

The following walkthrough creates a small panoramic information experience and puts its build under GitLab’s control.

Build a React 360 Project with a GitLab Workflow

1. Generate and run the application

Start with Git, Node.js, and npm installed. Use a Node version supported by the React 360 release you choose. For a 2019 project, Node 10 is a sensible starting point, subject to checking that release’s requirements.

The React 360 CLI can generate the initial project:

npm install -g react-360-cli
react-360 init PanoramaGuide
cd PanoramaGuide
npm start

Open the development URL printed in the terminal. The generated project typically separates the React interface in index.js from browser-side scene setup in client.js.

Keep that distinction clear:

• index.js defines the application’s React components.
• client.js initializes the runtime and places the application into the scene.
• static_assets/ holds images and other static resources.

Before changing anything, confirm that the generated example works. A known-good starting point makes it easier to distinguish setup problems from mistakes introduced by your own code.

2. Add a panoramic background

Place a licensed, equirectangular panoramic image in static_assets/, for example tour-panorama.jpg. A conventional full-sphere equirectangular panorama has a 2:1 aspect ratio; an ordinary wide photograph will not map correctly to the surrounding sphere.

In the generated client.js, find the background setup and update its asset path. Inside the initialization function, where r360 is available, the relevant call looks like this:

r360.compositor.setBackground(
  r360.getAssetURL('tour-panorama.jpg')
);

Keep the rest of the generated initialization code intact, including the code that mounts your React application onto a surface.

Choose an image with a clear horizon and avoid placing important visual details directly behind the interface. Start with a reasonably compressed image rather than the largest source file available. You can increase quality after testing loading time and appearance on your target devices.

3. Create an interactive information panel

Replace the generated component in index.js with a small interface. This example assumes the project was initialized as PanoramaGuide; the registered component name must match the name used in client.js.

import React from 'react';
import {
  AppRegistry,
  StyleSheet,
  Text,
  View,
  VrButton,
} from 'react-360';

class PanoramaGuide extends React.Component {
  state = {showDetails: false};

  toggleDetails = () => {
    this.setState(previous => ({
      showDetails: !previous.showDetails,
    }));
  };

  render() {
    return (
      <View style={styles.panel}>
        <Text style={styles.heading}>Explore the space</Text>
        <Text style={styles.copy}>
          Look around, then select the button to learn more.
        </Text>
        <VrButton onClick={this.toggleDetails} style={styles.button}>
          <Text style={styles.buttonLabel}>
            {this.state.showDetails ? 'Hide details' : 'Show details'}
          </Text>
        </VrButton>
        {this.state.showDetails && (
          <Text style={styles.copy}>
            This panel can describe a location, object, or next step.
          </Text>
        )}
      </View>
    );
  }
}

const styles = StyleSheet.create({
  panel: {
    width: 600,
    padding: 30,
    backgroundColor: 'rgba(0, 0, 0, 0.8)',
  },
  heading: {
    fontSize: 36,
    color: '#ffffff',
    marginBottom: 16,
  },
  copy: {
    fontSize: 24,
    color: '#ffffff',
    marginBottom: 16,
  },
  button: {
    padding: 18,
    backgroundColor: '#2458a6',
    marginBottom: 16,
  },
  buttonLabel: {
    fontSize: 24,
    color: '#ffffff',
  },
});

AppRegistry.registerComponent('PanoramaGuide', () => PanoramaGuide);

VrButton provides an interaction abstraction, but you still need to verify selection behavior on each intended device. Keep controls large, labels short, and text contrast high. A panel that looks compact on a monitor may be difficult to read in a headset.

4. Commit the project to GitLab

Create an empty GitLab repository, then connect the local project:

git init
git add .
git commit -m "Create React 360 panorama guide"
git remote add origin git@gitlab.com:YOUR_NAMESPACE/panorama-guide.git
git push -u origin HEAD

Before committing, check that .gitignore excludes node_modules/ and generated build output. Commit package-lock.json so local development and CI can install the same dependency versions.

Large media files deserve a deliberate policy. Git LFS can help manage large binary assets, but verify how those assets are retrieved during CI. For frequently changing or substantial media collections, external asset hosting may be more practical.

Use branches and merge requests for subsequent changes. Include a screenshot, the devices tested, and a brief description of interaction changes in each review.

5. Automate the production build

First, run the generated production command locally:

npm run bundle

Check package.json and inspect the output rather than assuming every CLI release produces an identical layout. Standard React 360 scaffolds include a bundling script that writes production files into build/.

A minimal .gitlab-ci.yml can make that build repeatable:

image: node:10

stages:
  - build

build_vr:
  stage: build
  script:
    - npm ci
    - npm run bundle
  artifacts:
    paths:
      - build/

This configuration is a historical starting point for the 2019 toolchain, not a recommendation to use Node 10 indefinitely. Pin and maintain dependencies according to your project’s support requirements.

A passing build proves that bundling succeeded. It does not prove that the scene renders correctly, assets load, or headset input works. Add linting and automated tests as the project grows, while retaining manual device checks.

6. Publish a verified static build

GitLab Pages can host the application if the production output is self-contained. Before deployment, verify that it includes an HTML entry point, the JavaScript bundles, and all referenced assets.

Once you have confirmed your scaffold’s output structure, extend the pipeline with a deployment stage and a Pages job:

# Add deploy after build in the existing stages list.
# stages:
#   - build
#   - deploy

pages:
  stage: deploy
  dependencies:
    - build_vr
  script:
    - mkdir -p public
    - cp -R build/. public/
    - cp -R static_assets public/
    - test -f public/index.html
  artifacts:
    paths:
      - public
  only:
    - master

This example assumes master is the production branch and that the generated build expects assets under static_assets/. Adjust both to match your project. If bundling already copies assets, omit the redundant copy. If it does not generate index.html, prepare a production entry page referencing the bundled files before enabling deployment.

Test the published URL, not just localhost. Project Pages sites may be served beneath a repository path, so root-relative asset URLs can fail. Use HTTPS and inspect the browser console and network panel for missing resources.

Common Pitfalls and Practical Checks

Confusing deployment with immediate availability

Pushing a commit does not instantly update every device. The pipeline must finish, hosting must publish the files, and browsers or content delivery caches may retain older resources. Confirm the deployed revision and use a deliberate cache strategy.

Treating visual review as optional

Automated tests are useful for state transitions and application logic. They cannot establish comfort, legibility, or whether a visitor understands where to look. Review the experience at realistic viewing sizes and inside supported headsets.

Avoid unnecessary camera movement. Let users control exploration, and keep essential controls easy to locate.

Ignoring the non-VR experience

Not every visitor has a headset or a compatible browser. Provide clear desktop instructions and a usable touch experience where supported. For essential information, consider an ordinary HTML alternative: immersive rendering alone is not a complete accessibility strategy.

Publishing oversized or sensitive assets

A panorama can dominate the initial download. Compress images, remove unused assets, and test on a slower connection. Also inspect photographs for private information and confirm usage rights before publishing them.

Remember that client-side bundles and static assets are public. Never embed credentials or private API secrets in the application.

Takeaway

React 360 and GitLab form a useful combination, but they solve different problems. React 360 builds the immersive interface; GitLab makes its development, review, and delivery repeatable. Start with one panorama and one clear interaction, verify the production build, and test the deployed experience on real target devices before expanding the scene.