magnyte-preview-sdk

v1.0.3

Published

11 days ago

Zero-config preview links with live collaboration features for any site. Auto-generates preview URLs with live cursors, annotations, and team collaboration.

🚀 Magnyte Preview SDK

Zero-config live preview links with real-time collaboration

Generate instant preview URLs for your deployed apps with built-in live cursors, annotations, and team collaboration features.

Dashboard · Get API Key · Documentation

✨ Features

🎯 Zero Configuration – Auto-detects Vercel, Netlify, Railway, Render, Heroku, and VPS
👥 Live Collaboration – Real-time cursors and annotations on previews
🔒 Hidden Mode – Keyboard shortcut activation for production sites (Ctrl+Shift+M)
🔧 Multi-Framework – Express, Next.js, React, Vite, Vanilla JS support
📊 Instant Dashboard – All preview links auto-sync to your dashboard
🌍 Universal – Works on any hosting platform
💪 TypeScript – Full type definitions included
📦 Lightweight – Minimal dependencies (~50KB)

📦 Installation

npm install magnyte-preview-sdk

🚀 Quick Start (Zero Config)

1. Get Your API Key

Visit Dashboard → API Keys to generate your API key.

2. Add to Your Frontend

Option A: Vanilla JS/HTML (Just add this to your HTML):

<script src="https://unpkg.com/magnyte-preview-sdk/dist/client.js" data-api-key="mp_live_xxx"></script>

Option B: React/Vue/Vite:

import { initClient } from 'magnyte-preview-sdk/client';

initClient({ apiKey: 'mp_live_xxx' });

Option C: React Hook:

import { useMagnytePreview } from 'magnyte-preview-sdk/middleware/react';

function App() {
  useMagnytePreview({ apiKey: 'mp_live_xxx' });
  return <div>Your app</div>;
}

3. Deploy

Deploy your app normally. Your preview URL appears automatically in the dashboard!

That's it! No backend code needed! ✅

🔒 Hidden Mode (Production Sites)

By default, collaboration features are hidden on production sites to prevent random visitors from seeing them. Team members can activate collaboration by pressing:

Ctrl+Shift+M (⌘+Shift+M on Mac)

How It Works

Production (Netlify/Vercel): Collaboration hidden until keyboard shortcut pressed
Development (localhost): Collaboration always visible
Persistent: Activation saved in localStorage (stays enabled on return)

Configuration

// Auto-hidden in production (default)
useMagnytePreview({ apiKey: 'mp_live_xxx' });

// Force visible (even in production)
useMagnytePreview({ apiKey: 'mp_live_xxx', hiddenMode: false });

// Force hidden (even in development)
useMagnytePreview({ apiKey: 'mp_live_xxx', hiddenMode: true });

Console Commands

// Deactivate collaboration (clears localStorage and reloads)
window.MagnytePreview.deactivateCollaboration();

📖 Usage Examples

Vanilla JavaScript / HTML

Zero Config - Just add to your index.html:

<script src="https://unpkg.com/magnyte-preview-sdk/dist/client.js" 
        data-api-key="mp_live_xxx"></script>

React (Any Setup)

Option 1: Hook in App Component

import { useMagnytePreview } from 'magnyte-preview-sdk/middleware/react';

function App() {
  useMagnytePreview({ apiKey: process.env.REACT_APP_MAGNYTE_KEY });
  return <div>Your app</div>;
}

Option 2: Provider Component

import { MagnyteProvider } from 'magnyte-preview-sdk/middleware/react';

function Root() {
  return (
    <MagnyteProvider apiKey="mp_live_xxx">
      <App />
    </MagnyteProvider>
  );
}

Next.js (App Router)

app/providers.tsx (Client Component):

'use client';
import { useMagnytePreview } from 'magnyte-preview-sdk/middleware/react';

export function Providers({ children }) {
  useMagnytePreview({ apiKey: process.env.NEXT_PUBLIC_MAGNYTE_KEY });
  return <>{children}</>;
}

app/layout.tsx:

import { Providers } from './providers';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Vue.js

main.js:

import { initClient } from 'magnyte-preview-sdk/client';

initClient({ apiKey: 'mp_live_xxx' });

createApp(App).mount('#app');

🔧 Advanced: Server-Side Integration

[!NOTE] Server-side integration is optional and only needed for advanced use cases. The client-side approach above is recommended for most users.

Express.js

const express = require('express');
const Magnyte = require('magnyte-preview-sdk');
const { magnyteMiddleware } = require('magnyte-preview-sdk/middleware/express');

const app = express();

await Magnyte.init({ apiKey: process.env.MAGNYTE_API_KEY });
app.use(magnyteMiddleware());

app.listen(3000);

⚙️ Configuration

API Key (Required)

await Magnyte.init({
  apiKey: 'mp_live_your_api_key_here'
});

Or use environment variables:

# .env
MAGNYTE_API_KEY=mp_live_your_api_key_here

Custom Backend (Optional)

For local testing or self-hosted instances:

await Magnyte.init({
  apiKey: 'mp_live_...',
  apiUrl: 'http://localhost:3000'
});

VPS Configuration (Optional)

If auto-detection doesn't work on your VPS:

# .env
MAGNYTE_PUBLIC_URL=https://your-domain.com

🌍 Supported Platforms

Auto-Detected

✅ Vercel · ✅ Netlify · ✅ Railway · ✅ Render · ✅ Heroku

Manual Configuration

✅ DigitalOcean · ✅ AWS EC2 · ✅ Linode · ✅ Google Cloud · ✅ Azure · ✅ Any VPS

Process Managers

✅ PM2 · ✅ Kubernetes · ✅ Docker

📚 API Reference

`init(config)`

Initialize the SDK.

Parameters:

config.apiKey (string, required) – Your Magnyte API key
config.apiUrl (string, optional) – Custom backend URL
config.hiddenMode (boolean, optional) – Hide collaboration until Ctrl+Shift+M (auto-enabled for production)
config.autoInit (boolean, optional) – Auto-initialize on load

Returns: Promise<void>

`getInstance()`

Get the initialized SDK instance.

Returns: MagnyteSDK | null

Example:

const instance = Magnyte.getInstance();
const previewUrl = instance?.getPreviewUrl();

🔄 How It Works

┌─────────────┐      ┌──────────────────┐      ┌─────────────────┐
│  Deploy App │  =>  │ Auto-Detect      │  =>  │ Register with   │
│             │      │ Platform         │      │ Magnyte Backend │
└─────────────┘      └──────────────────┘      └─────────────────┘
                                                         ↓
┌─────────────┐      ┌──────────────────┐      ┌─────────────────┐
│ QA Testing  │  <=  │ Dashboard Sync   │  <=  │ Generate        │
│             │      │                  │      │ Preview URL     │
└─────────────┘      └──────────────────┘      └─────────────────┘

Step-by-Step:

Deploy → Push your app to Vercel, Netlify, Railway, VPS, etc.
Auto-Detect → SDK automatically detects your hosting platform
Register → Sends deployment URL to Magnyte backend
Generate → Receives unique preview URL (e.g., vercel-abc123.magnytepreview.magnytesolution.com)
Dashboard → Preview link appears instantly in your dashboard
Collaborate → Team tests with live cursors & annotations

🔧 Environment Variables

| Variable | Required | Description | Default | |----------|----------|-------------|---------| | MAGNYTE_API_KEY | Yes* | Your API key | - | | MAGNYTE_API_URL | No | Custom backend URL | https://mspreviewbackend.magnytesolution.com | | MAGNYTE_PUBLIC_URL | No | Manual URL for VPS | Auto-detected |

*Required only if not passed in code

💡 Use Cases

QA Testing – Share preview links for pre-production testing
Client Demos – Show work-in-progress without deploying to production
Team Collaboration – Review changes with real-time cursors
Staging Environments – Test deployment-specific features
Bug Reporting – Add visual annotations directly on UI

🛠️ Troubleshooting

Preview not showing?

# Check if API key is correct
# View logs for [Magnyte] messages
# Ensure NODE_ENV=production

VPS auto-detection failed?

# Set manual URL override
export MAGNYTE_PUBLIC_URL=https://your-domain.com

Local testing?

await Magnyte.init({
  apiKey: 'mp_live_...',
  apiUrl: 'http://localhost:3000' // Local backend
});

📝 Import Styles

Both import patterns are supported:

// Namespace import (recommended)
import * as Magnyte from 'magnyte-preview-sdk';
await Magnyte.init({ apiKey: '...' });

// Named imports
import { init, getInstance } from 'magnyte-preview-sdk';
await init({ apiKey: '...' });

// CommonJS
const Magnyte = require('magnyte-preview-sdk');
await Magnyte.init({ apiKey: '...' });

🤝 Support

📧 Email – [email protected]
🐛 Issues – GitHub Issues
📖 Docs – magnytepreview.magnytesolution.com
💬 Contact – Dashboard Support

📄 License

See LICENSE for details.

🔗 Links

Made with ❤️ by Magnyte Software