WebXR Webpack Boilerplate

Starter Kit for building rich, immersive WebXR projects (featuring A-Frame) PWA with Webpack and SASS

Introduction

The goal of WebXR Webpack Boilerplate is to provide a high-quality, high-performance code base to accelerate WebXR development. It is designed to be flexible in order to support rapid implementation and customization within your project. — take a look at demo

Project build status

Linux	macOS	Windows

---

• Overview
  • Project structure
  • Custom A-Frame Theme
• Getting Started
  • Fork this repository
    • (option 1) Create fork to contribute back to this repository
    • (option 2) Create new Open Source project based on this repository
    • (option 3) Create new private project based on this repository
  • First run
  • Build Configuration
    • Add A-Frame components
    • Add 3rd party libraries
    • Build or rebuild 3rd party libraries

---

Overview

here is overview of WebXR Webpack Boilerplate project and what's included.

Frameworks

• 

Project structure

• build development and staging build output directory
• devel development related files like webpack and project configuration files.
  • coverage coverage report (#2)
• dist project release files, output of yarn run dist.
• docs project documentation or can be used for gh-pages
• res all static and raw resources which are rather src files for src/assets e.g raw design files.
  • audio audio files
  • images image files
  • models 3D objects and models
  • video video files
• src project source files.
  • aframe A-Frame compnents,systems.shaders
    • components custom components
    • primitives custom primitives
    • shaders custom shaders
    • systems custom systems
  • api dummy API
  • assets project assets which may be processed by Webpack if rule is set in Webpack configuration
    • static all assets are just copied to {build}/assets/static
  • js main application
  • partials partials for handlebars
    • aframe partials for A-Frame scenes
    • html partials for HTML pages
    • ... your own partials structure
  • scenes all your A-Frame scenes or HTML pages
  • style project styles
    • config style configuration
      • themes style themes
      • vendor vendor sass files
    • app your app styles
• tests test suites.
• tmp temporary and local files which are not tracked by git.

---

Custom A-Frame Theme

red	blue	green	yellow

You can change A-Frame themes by modifying SASS configuration $theme variable in src/style/app-theme.scss

// Color themes red !default, yellow, green, blue
$theme: red;

---

Getting Started

instructions to set up your project

Fork this repository

Follow one of the 3 options below

navigate to directory you keep your projects and set following temporary environment variables

cd <your-projects>
PROJECT_NAME="<your-new-project-dir-name>"
GITHUB_USERNAME="<github-username>"

for full copy you need git-lfs plugin for git

(option 1) Create fork to contribute back to this repository

clone full copy of this repository and set remotes to be able sync your repository with upstream

git clone --origin github/"$GITHUB_USERNAME" git@github.com:$GITHUB_USERNAME/webxr-webpack-boilerplate.git "$PROJECT_NAME"
cd "$PROJECT_NAME"
git remote add github/mkungla git@github.com:mkungla/webxr-webpack-boilerplate.git

^{and start hacking.}

(option 2) Create new Open Source project based on this repository

clone minimal copy of this repository and set remotes for your new repository.
Your repository GitHub project URL should be in form of
https://github.com/$GITHUB_USERNAME/$PROJECT_NAME
and repository should be new (clean repository)

GIT_LFS_SKIP_SMUDGE=1 git clone --depth=1 --origin github/"$GITHUB_USERNAME" git@github.com:$GITHUB_USERNAME/webxr-webpack-boilerplate.git "$PROJECT_NAME"
cd "$PROJECT_NAME"
rm -rf .git
git init
git remote set-url github/"$GITHUB_USERNAME" git@github.com:$GITHUB_USERNAME/"$PROJECT_NAME".git
git push github/"$GITHUB_USERNAME" master

^{and start hacking.}

(option 3) Create new private project based on this repository

GIT_LFS_SKIP_SMUDGE=1 git clone --depth=1 --origin github/"$GITHUB_USERNAME" git@github.com:"$GITHUB_USERNAME"/webxr-webpack-boilerplate.git "$PROJECT_NAME"
cd "$PROJECT_NAME"
rm -rf .git
git init
# add your private remote

^{and start hacking.}

First run

By default yarn start will not build vendor libraries to improve webpack-dev-server performance a bit. Vendor libraries are only built when running yarn run build or yarn run dist

brew install yarn

yarn install
yarn run build
yarn start

Build Configuration

Modify package.json devSettings

key	description
host	host for webpack dev server, default localhost and set it 0.0.0.0 to share it on your LAN
port	port to use by webpack dev server
allowedHosts	[] array of allowed hosts

Add A-Frame components

yarn add -D <some-aframe-component>

add import statement to ./src/aframe/aframe-base.js

Add 3rd party libraries

yarn add -D <some-library>

optionally add import statement to ./src/js/vendors.js if you want to bundle that dependency together with other 3rd party libraries

Build or rebuild 3rd party libraries*

when you want to update/rebuild vendor libraries you have to run yarn run build before yarn start.

• ./src/aframe-base.js where you import A-Frame and external A-Frame components.
• ./src/js/vendors.js where you import any other 3rd party libraries

however if you some reason want to rebuild and watch vendor libraries while developing you can enable that by setting environment variable.

WITH_VENDORS="true" yarn start

---