Block Settings
Every setting on the BITBYBIT APPS block, which you find in the theme editor after adding the block to a template. The "BITBYBIT APPS" Block explains what the block is for, when to use it and the workflow from localhost to live.
BITBYBIT APPS is available on the Pro subscription plan only. On any other plan the block does not appear in the theme editor's Add block list at all, and its runtime is never loaded, so if you cannot find it, check your subscription first rather than your theme. A block already placed in a template stops rendering if the Pro subscription lapses. See Subscription plans.
Public Script URL
Which JavaScript application the block loads. Public Script URL covers hosting and CORS, and the value decides which of three modes you are in:
| Mode | Set it to | What the block does |
|---|---|---|
| Local development | Nothing, leave it empty | Embeds https://localhost:4242 in an iframe, so your development server has to answer there, over HTTPS. |
| Preview | Your local static build, such as https://localhost:4242/assets/index-stable.js | Loads the file as a module, the way production does. |
| Production | Your file's CDN address, such as https://cdn.shopify.com/s/files/1/xxx/index-<hash>.js?version=<version> | The same, for your shoppers. |
Switching between them needs no change to your code. Anything that does not start with https:// loads nothing, and the theme editor shows a notice saying so.
Unlike the other blocks, APPS usually serves one application across all products, which reads the product from the inputs it receives and adapts. So this setting usually stays global, unless you are building different applications for different product categories, when you can link it to a metafield.
Application requirements
Your application has to be:
- An ES module: the block loads it with
<script type="module">. - One JavaScript file, with its styles bundled in. The block loads nothing else.
- Built on the
bits-propackage, which is how it receives Shopify's data. - Allowed cross-origin, if it is on another domain. The block loads it with CORS, which Shopify's CDN answers on its own. Whoever can change the file at that address changes what runs on your product pages, so in production keep it under Content then Files in your own Shopify admin.
Our templates are set up this way. Vite is what they use, and other bundlers may work but are not what we test against. A custom setup should output one ES module file, and serve on port 4242 in development.
Your application and bits-pro
Your application talks to the block through the @bitbybit-dev/bits-pro package, in three calls:
bitsPro.init(onUpdate, isProduction)registers the function that receives the inputs. Call it first. Passimport.meta.env.PROD, as the two modes reach the block differently: an iframe in development and the page in production.bitsPro.appReady()tells the block you are ready, and only then does it start sending inputs.bitsPro.finishedComputing()tells the block you have finished with a set of inputs, which is what clears the spinner and frees the form.
The inputs are a plain object of the names and values on the page, plus a bitsContext holding iterationCount, which goes up with each update, and blockId, the block your application runs in, which the very first update does not carry yet.
import { bitsPro } from "@bitbybit-dev/bits-pro";
import { createDirLightGroundAndSphere, initThreeJS } from "./init-threejs"
document.querySelector<HTMLDivElement>('#root-3d-bits')!.innerHTML = `
<div id="scene-container" style="width: 100%; height: 100%; overflow: hidden;">
<canvas id="three-canvas"></canvas>
</div>
`
interface Inputs {
// Input names and their values are assembled by 3D Bits, this interface should reflect your
// actual set up. You may need to use case-sensitive strings to define the properties.
[key: string]: unknown;
bitsContext: {
// normally starts with 0 and increases each time the inputs on
// Shopify side change
iterationCount: number;
// the ID of the current HTML block context where your app is running
blockId: string;
}
}
const onUpdate = async (inputs: Inputs) => {
console.log('Inputs Received:', inputs);
// In case you use spinners or disable inputs on Shopify side, you can
// enable them again by calling this function. It is good practice to await
// all of the code to be finished before calling this function.
bitsPro.finishedComputing();
}
const start = async () => {
// Always needs to be initialized first by providing the onUpdate function
bitsPro.init(onUpdate, import.meta.env.PROD);
const canvas = document.getElementById('three-canvas') as HTMLCanvasElement;
const { scene } = initThreeJS(canvas);
// When the app is initialized we must call this function
// to let the Shopify side know that the app is ready to send updates on changing inputs
setTimeout(() => {
bitsPro.appReady();
});
}
start();
Settings shared with other blocks
Each of these is documented once, in Common Settings. This is what is particular to the APPS block.
| Setting | On this block |
|---|---|
| Show Spinner | Shows while your application starts. After that it shows each time the block sends new inputs, and hides when your application calls bitsPro.finishedComputing(), so make that call once the change is drawn. |
| Receive Input Names As Variants | Decides the keys of the object your onUpdate receives. |
| Input Collection Mode | Decides which fields reach your application. Use All Inputs if it needs hidden fields. |
| Enable Debug Mode | Prints the inputs and the block's settings as JSON, to check what your application receives. |
| Disable Inputs When Computing | The same handshake as the spinner: inputs are disabled when the block sends new ones, and enabled again when your application calls bitsPro.finishedComputing(). |
| Show Fullscreen Button | Fullscreens the block. Your application can add its own behaviour as well. |
Try to Prepend, Prepend With Query Selector and Remove Children Before Prepend are on this block in the theme editor, but they do not move it. The application stays where you place the block, so position it there.
Pricing
Any price your application works out in the browser has to be checked by something you trust. Pricing and backend logic sets out the options.
Verified against the product in November 2026