Phoenix Three

View Source

A Mix task package for easily integrating Three.js into Phoenix projects. Automatically downloads Three.js files from CDN and configures your app.js imports.

Features

  • One-command setup - Download and configure Three.js with a single command
  • Version control - Specify which Three.js version to download
  • Smart imports - Automatically adds imports to your app.js file
  • Global access - Makes THREE available globally for LiveView hooks
  • Idempotent - Safe to run multiple times, won't duplicate imports
  • Phoenix optimized - Follows Phoenix asset conventions

Installation

Add phoenix_three to your list of dependencies in mix.exs:

def deps do
  [
    {:phoenix_three, github: "benjaminjacobberg/phoenix_three", only: :dev, runtime: false}}
  ]
end

Then run:

mix deps.get

Usage

Quick Start

Set up Three.js in your Phoenix project with one command:

mix threejs.setup

This will:

  1. Download Three.js files to assets/vendor/three/
  2. Add the import to your assets/js/app.js
  3. Make THREE available globally for hooks

Individual Commands

Download Three.js files only:

mix threejs.download

Configure app.js imports only:

mix threejs.configure

Options

Version Selection:

# Download specific Three.js version
mix threejs.setup --version 0.176.0

Force Overwrite:

# Overwrite existing files and imports
mix threejs.setup --force

What Gets Added to Your Project

Files Downloaded

  • assets/vendor/three/three.module.js - Main ES6 module
  • assets/vendor/three/three.core.js - Core library
  • assets/vendor/three/three.webgpu.js - WebGPU renderer
  • assets/vendor/three/three.webgpu.nodes.js - WebGPU nodes
  • assets/vendor/three/three.tsl.js - Three Shading Language

App.js Modifications

The task adds this import to your assets/js/app.js:

import * as THREE from "../vendor/three/three.module.js";

And this global assignment after your window.liveSocket = liveSocket line:

// Make THREE.js available globally for hooks
window.THREE = THREE

Using Three.js in LiveView Hooks

After setup, you can use Three.js in your Phoenix LiveView hooks:

// assets/js/app.js
let Hooks = {}

Hooks.ThreeScene = {
  mounted() {
    // THREE is available globally
    const scene = new THREE.Scene()
    const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000)
    const renderer = new THREE.WebGLRenderer()

    renderer.setSize(this.el.clientWidth, this.el.clientHeight)
    this.el.appendChild(renderer.domElement)

    // Your Three.js code here...
  }
}

let liveSocket = new LiveSocket("/live", Socket, {hooks: Hooks, params: {_csrf_token: csrfToken}})

In your LiveView template:

<div id="three-container" phx-hook="ThreeScene"></div>

Integration with Build Process

Add to your mix.exs aliases for automatic setup:

defp aliases do
  [
    setup: ["deps.get", "threejs.setup", "assets.setup", "assets.build"],
    "assets.deploy": ["threejs.setup", "assets.deploy"]
  ]
end

Available Three.js Versions

The package downloads from CDNJS. You can use any version available there:

  • Latest: mix threejs.setup (currently 0.177.0)
  • Specific: mix threejs.setup --version 0.176.0
  • Legacy: mix threejs.setup --version 0.150.0

Troubleshooting

"assets/js/app.js not found" error:

  • Make sure you're running the command from your Phoenix project root
  • Ensure your Phoenix project has the standard asset structure

Import conflicts:

  • Use --force flag to overwrite existing imports
  • Manually check your app.js if imports look incorrect

Version not found:

  • Check available versions at CDNJS Three.js
  • Some very new versions might not be available on CDNJS yet

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/benjaminjacobberg/phoenix_three.

License

The package is available as open source under the terms of the MIT License.

Credits