Skip to content

Integrate an existing Web project

Get Hello Web working first, then integrate the same manifest, SDK initialization, and permission declarations into your project. This guide uses an existing Vite project to explain source and packaging directories.

Step 1: organize the project files#

Copy the standalone SDK from “Your first Web plugin” to src/vendor and import it in src/main.js through ./vendor/gm-plugin-web-sdk.esm.js. With existing framework components, create one SDK instance during application initialization.

Place the complete Web manifest in public/manifest.json so Vite copies it to the dist root. Set your own id, name, and version, keep entry as index.html, and declare the permissions you actually use.

Directory structure
PhoneSDK/examples/my-web-app/
├── package.json
├── package-lock.json
├── vite.config.js
├── index.html
├── src/
│   ├── main.js
│   └── vendor/gm-plugin-web-sdk.esm.js
├── public/
│   └── manifest.json
└── dist/                      # Generated by the frontend build

Step 2: use relative asset paths#

Merge the following settings into your existing vite.config.js/ts, preserving its plugins and other configuration. The entry index.html references your src/main.js, and Vite bundles the SDK and business JavaScript.

< / >
export default {
  base: './',
  build: { outDir: 'dist' }
};

Step 3: let the script build and package the project#

The project is already at PhoneSDK/examples/my-web-app. Return to PhoneSDK and run one command. The script discovers public/manifest.json and the parent package.json.

On the first run or after dependency declarations change, the script runs npm ci or npm install according to the lockfile, then npm run build, and packages dist as PhoneSDK/dist/my-web-app-0.1.0.mmpkg. Run the same command after future source changes; unchanged projects are skipped.

macOS / Linux

< / >
./build.py

Windows PowerShell

< / >
py build.py

Step 4: check the generated artifacts#

  1. Edit the source public/manifest.json and rebuild. Do not edit only dist/manifest.json, which the next frontend build regenerates.
  2. Confirm that dist/manifest.json and dist/index.html both exist.
  3. Confirm that all referenced scripts, styles, and images are in dist and that the SDK is bundled into the scripts or copied as a static file.
  4. Confirm that dist contains no node_modules, test data, or unnecessary source maps. The packager recursively collects the input directory and does not exclude these files automatically.
  5. Confirm that PhoneSDK/dist/my-web-app-0.1.0.mmpkg was generated, with the version determined by the manifest.

Step 5: import into Studio and verify on a phone#

  1. Use Studio's Import package to import the generated my-web-app-0.1.0.mmpkg and run the final built assets.
  2. Use GM Web Bridge for standard display, or the matching GMP for a custom paired protocol.
  3. Verify the handshake, page interactions, and glasses display, then wait for ZIP packaging to finish before scanning.
  4. Stop the computer's frontend development server, generate a new QR code in Studio, and scan again with the App. If the page and assets still load, the runtime files are complete.

Reference files in the toolkit#

  • PhoneSDK/docs/web-plugin/developer-guide.md
  • PhoneSDK/examples/tic-tac-toe/vite.config.ts
  • PhoneSDK/build.py
  • PhoneSDK/tools/build-mmpkg.mjs