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:

1. One-Click Deployment Components (Recommended)

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:

• Needle Cloud – Official hosting with CLI support

• Netlify – Professional hosting

• Vercel – Frontend-optimized

• GitHub Pages – Free static hosting

• FTP – Any web server

• itch.io – Game hosting

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

:::tip 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 →

:::tip 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!

:::tip 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>

:::tip 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:

Option	Example	When to Use
Needle Cloud	myproject.needle.run	Prototypes, development, demos
Subpage	client-site.com/app	Part of existing site
Subdomain	app.client-site.com	Separate but branded
Domain	my-app.com	Standalone product

:::tip 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?

:::tip 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 Manager

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

Framer

Integrate Needle Engine scenes into Framer websites.

WordPress

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

Shopify

:::warning Under Construction Shopify integration guide coming soon. In the meantime, use the iframe method for quick integration. :::

Webflow

:::warning Under Construction Webflow integration guide coming soon. In the meantime, use the iframe method for quick integration. :::

Next Steps

Configuration & Customization:

• Web Component Attributes – Configure the <needle-engine> element

• Scripting Guide – Add custom functionality

• Deployment Options – Explore all hosting platforms

Editor Integrations:

• Unity Integration – Visual scene creation with Unity

• Blender Integration – Visual scene creation with Blender

Get Help:

• Forum – Ask questions and share projects

• Discord – Join our community

• FAQ – Common questions and troubleshooting

:::tip 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.

Learn about Unity Integration • Learn about Blender Integration :::