Embedding Needle Engine on Your Website

Add interactive 3D to any website. Needle Engine can be integrated into existing websites, embedded in CMSs like WordPress, or deployed as standalone web apps. This guide covers all the ways to get your 3D content live.

Quick Test: 2-Minute Integration

Want to see how Needle Engine looks on your website? Add these two lines anywhere on your page:

<!-- Import the component -->
<script type="module" src="https://cdn.jsdelivr.net/npm/@needle-tools/engine/dist/needle-engine.min.js"></script>

<!-- Use it like any other HTML element -->
<needle-engine src="https://cloud.needle.tools/-/assets/Z23hmXBZ21QnG-Z21QnG-world/file" background-color="transparent"></needle-engine>

Open this example on StackBlitz

Deployment Methods

Choose the approach that fits your workflow:

Best for: Quick iterations, multiple hosting platforms, team workflows

Our Unity and Blender integrations include built-in deployment components. Deploy to multiple platforms with just a few clicks.

Supported platforms:

How it works:

From Unity or Blender:

  1. Add the "Deploy to..." component to your scene
  2. Configure the necessary options
  3. Click "Deploy"

From Command Line (Needle Cloud):

# Deploy to Needle Cloud from any web project
npx needle-cloud deploy

Learn more about deployment options • Needle Cloud CLI docs

Recommended Workflow

This is the easiest and fastest option. Iterate locally, then upload a new version in seconds.

2. Command-Line Deployment (Needle Cloud)

Best for: CI/CD pipelines, automation, web-only projects, developers

Deploy to Needle Cloud directly from the command line without Unity or Blender.

Steps:

  1. Navigate to your web project folder (the one with package.json)
  2. Run the deploy command:
npx needle-cloud deploy
  1. Follow the prompts to:
    • Log in to your Needle Cloud account (if not already logged in)
    • Choose or create a project
    • Confirm deployment

Features:

  • ✅ Works from any web project – No editor needed
  • ✅ Automatic builds – Builds and optimizes before uploading
  • ✅ Fast updates – Incremental uploads for quick iterations
  • ✅ CI/CD ready – Perfect for automated workflows

Learn more about Needle Cloud CLI →

Automated Deployment

Add npx needle-cloud deploy --ci to your GitHub Actions or other CI/CD pipeline for automatic deployments on every commit.

3. Manual Build & Upload

Best for: Custom workflows, unsupported hosting platforms

Build your project and manually upload the distribution files to any web server.

Steps:

  1. Create a production build of your web project
    • This generates a dist/ folder with all files
  2. Upload the contents of the dist/ folder to your web host
    • Use FTP, SFTP, or your host's file manager
  3. Your web app is live!

URL Structure

The folder location determines your app's URL:

  • Domain: https://your-website.com/ points to /var/www/html
  • Upload to: /var/www/html/my-app/
  • Your URL: https://your-website.com/my-app/

4. iframe Embedding

Best for: Limited website access, CMS platforms (WordPress, Wix), quick embeds

Embed your Needle Engine scene like you would a YouTube video.

Steps:

  1. Build and upload your project to any web host
  2. Add an iframe to your website:
<iframe
    src="https://your-website.com/needle-files/dist/index.html"
    allow="xr; xr-spatial-tracking; fullscreen;"
    style="width: 100%; height: 600px; border: none;">
</iframe>

Required Permissions

The allow attribute depends on your app's features:

  • XR apps: xr; xr-spatial-tracking
  • Fullscreen: fullscreen
  • Camera/Mic: camera; microphone
  • More features: accelerometer; gyroscope; display-capture; geolocation

See full list of iframe permissions →

5. Direct Integration (Advanced)

Best for: Existing websites, custom layouts, advanced control

Embed a Needle Engine project directly into an existing webpage's HTML.

Steps:

  1. Build your project (creates a dist/ folder)
  2. Upload the dist/ folder to your web host
  3. Open dist/index.html in a text editor and find these lines:
<head>
    <script type="module" crossorigin src="./assets/index-732f0764.js"></script>
</head>
<body>
    <needle-engine src="assets/scene.glb"></needle-engine>
</body>
  1. Copy both lines to your target website, updating paths:
<script type="module" src="/your-upload-folder/assets/index-732f0764.js"></script>
<needle-engine src="/your-upload-folder/assets/scene.glb"></needle-engine>

6. CDN for Core Components Only

Best for: Projects without custom scripts, quick prototypes, simple scenes

Use Needle Engine directly from a CDN without uploading any JavaScript bundles.

Requirements: Your project must use only core Needle Engine components (no custom scripts).

Steps:

  1. Add the CDN script to your website:
<script type="module" src="https://cdn.jsdelivr.net/npm/@needle-tools/engine/dist/needle-engine.min.js"></script>
<needle-engine src="https://your-website.com/assets/MyScene.glb"></needle-engine>
  1. Upload your assets/ folder to your web host
    • Contains .glb files and other assets (audio, video, skybox, etc.)
  2. Update the src attribute to point to your uploaded .glb file

7. Needle Cloud iframe

Best for: Projects hosted on Needle Cloud, quick sharing, portfolios

If you've deployed to Needle Cloud, embed it anywhere with a simple iframe.

How to get the embed code:

  1. Go to your asset page on Needle Cloud
  2. Click the "Embed" button
  3. Copy the generated iframe code
<iframe
    src="https://cloud.needle.tools/view/embed?file=Z23hmXBZ21QnG-Z21QnG-world"
    title="Your Project | Hosted on Needle Cloud"
    style="width: 100%; height: 600px"
    frameborder="0"
    allow="xr-spatial-tracking; accelerometer; gyroscope; display-capture; geolocation; camera; microphone"
    allowfullscreen>
</iframe>

Common Workflows

Client Projects: Professional Deployment

When building a web app for a client, consider these factors:

1. Determine the Type of Application

  • Standalone app – Accessible via a link on the client's domain
  • Integrated app – Part of existing website with server-side/client-side components
  • Embedded experience – Inside a CMS or existing page

2. Choose the URL Structure

The app can be hosted at:

OptionExampleWhen to Use
Needle Cloudmyproject.needle.runPrototypes, development, demos
Subpageclient-site.com/appPart of existing site
Subdomainapp.client-site.comSeparate but branded
Domainmy-app.comStandalone product

Development to Production

Start on Needle Cloud for prototypes and development, then move to the client's domain for the final version. This approach balances speed with branding requirements.

3. Plan Deployment & Maintenance

Access & Updates:

  • Will you have FTP/SFTP access to upload updates?
  • Will the client manage deployments?
  • How often does content need updating?

FTP Access

Request FTP/SFTP access to a folder on the client's server. Use our Deploy to FTP component for easy uploads. The client's IT team handles URL configuration.

Content Type:

  • Static content – Occasional updates via new builds
  • Dynamic content – May need CMS or database integration

Target Audience:

  • Which devices and browsers do users have?
  • Test on actual target devices (especially for AR/VR)

4. Set Up Test & Production Environments

Test the deployment process early:

  1. Set up a test environment (your own server or subdomain)
  2. Practice the deployment workflow
  3. Get client approval on test environment
  4. Deploy to production environment

5. Development Workflow

Iterate efficiently:

  1. Develop and test locally
  2. Deploy to test server for client review
  3. After approval, deploy to production server
  4. Repeat as needed

Platform-Specific Integrations

Adobe Experience ManagerAdobe Experience Manager

Integrate Needle Engine into AEM with custom components, Experience Fragments, and author-friendly workflows.

FramerFramer

Integrate Needle Engine scenes into Framer websites.

WordPressWordPress

Embed Needle Engine in WordPress posts, pages, and custom themes.

ShopifyShopify

Under Construction

Shopify integration guide coming soon. In the meantime, use the iframe method for quick integration.

WebflowWebflow

Under Construction

Webflow integration guide coming soon. In the meantime, use the iframe method for quick integration.

Next Steps

Configuration & Customization:

Editor Integrations:

Get Help:

  • Forum – Ask questions and share projects
  • Discord – Join our community
  • FAQ – Common questions and troubleshooting

Visual Scene Creation

Did you know Needle Engine integrates with Unity and Blender? Create complex 3D scenes visually and export them directly to the web. Perfect for non-coders or teams with 3D artists.

UnityLearn about Unity Integration • BlenderLearn about Blender Integration