Skip to main content

Integrate the SDK

|

Add the package​

The Magic Lane Maps SDK for TypeScript is available as an npm package.

Using npm​

npm install @magiclane/maps-sdk

Using yarn​

yarn add @magiclane/maps-sdk

Using pnpm​

pnpm add @magiclane/maps-sdk

Get Your API Token​

To use the Maps SDK, you need an API token from Magic Lane.

  1. Visit the Magic Lane Developer Portal
  2. Sign up or log in to your account
  3. Create a new project or select an existing one
  4. Copy your API token from the project dashboard
important

Keep your API token secure! Never commit it directly to version control or expose it in client-side code that's publicly accessible. Consider using environment variables for token management.

Basic Setup​

HTML Setup​

Create an HTML file with a container for the map:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Magic Lane Maps</title>
    <style>
        body, html {
            margin: 0;
            padding: 0;
            width: 100%;
            height: 100%;
        }
        #map-container {
            width: 100%;
            height: 100%;
        }
    </style>
</head>
<body>
    <div id="map-container"></div>
    <script type="module" src="/src/main.ts"></script>
</body>
</html>

TypeScript/JavaScript Setup​

Create your main TypeScript/JavaScript file:

import { GemKit, GemMap } from '@magiclane/maps-sdk';

// Initialize GemKit with your API token
const gemKit = await GemKit.initialize('YOUR_API_TOKEN_HERE');

// Get the map container element
const container = document.getElementById('map-container');
if (!container) throw new Error('Map container not found');

// Create the map view
const viewId = 1;
const wrapper = gemKit.createView(viewId, (gemMap: GemMap) => {
    console.log('Map initialized successfully!');
    // Your map is ready to use
});

if (wrapper) {
    container.appendChild(wrapper);
}

If you're using Vite, create or update your vite.config.ts:

import { defineConfig } from 'vite';

export default defineConfig({
    server: {
        port: 3000,
        headers: {
            // Required for WebAssembly
            'Cross-Origin-Opener-Policy': 'same-origin',
            'Cross-Origin-Embedder-Policy': 'require-corp'
        }
    },
    optimizeDeps: {
        exclude: ['@magiclane/maps-sdk']
    }
});

For better security, use environment variables for your API token.

Create .env file:​

VITE_MAGICLANE_API_TOKEN=your_api_token_here

Update your code:​

import { GemKit } from '@magiclane/maps-sdk';

const apiToken = import.meta.env.VITE_MAGICLANE_API_TOKEN;
if (!apiToken) {
    throw new Error('API token not found. Please set VITE_MAGICLANE_API_TOKEN in your .env file');
}

const gemKit = await GemKit.initialize(apiToken);

Add .env to .gitignore:​

# .gitignore
.env
.env.local

Verify Installation​

Run your development server:

npm run dev

Open your browser and navigate to the local server URL (typically http://localhost:3000). You should see a basic map displayed in the browser.

Common issues and troubleshooting

WebAssembly not loading​

Make sure your server is configured to serve .wasm files with the correct MIME type. Most modern development servers handle this automatically, but you may need to configure your production server.

CORS errors​

The SDK requires proper CORS headers. Make sure your development server is configured with:

  • Cross-Origin-Opener-Policy: same-origin
  • Cross-Origin-Embedder-Policy: require-corp

Module not found errors​

If you encounter module resolution errors:

  1. Clear your package manager cache: 
    npm cache clean --force
  2. Delete node_modules and lock file: 
    rm -rf node_modules package-lock.json
  3. Reinstall dependencies: 
    npm install

Map not displaying​

  • Verify your API token is correct and active
  • Check the browser console for error messages
  • Ensure the map container has explicit width and height
  • Verify your browser supports WebAssembly

Performance issues​

  • Make sure hardware acceleration is enabled in your browser
  • Check that you're not running too many concurrent operations
  • Consider reducing map detail level for lower-end devices

Next Steps​

Now that you have the SDK integrated, you can:

Last updated on