UNPKG

memberstack-ai-context

Version:

AI context server for Memberstack DOM documentation - provides intelligent access to Memberstack docs for Claude Code, Cursor, and other AI coding assistants

475 lines (387 loc) 11.4 kB
# Memberstack DOM - Initialization & Configuration ## AI Assistant Instructions When helping with Memberstack initialization: - Always include `publicKey` - it's required - Use `useCookies: true` for web apps (recommended) - Show both CDN and NPM usage patterns - Include error handling for initialization failures - Reference environment-specific endpoints when needed ## Overview The Memberstack DOM package must be initialized before any other methods can be used. Initialization creates a global instance and configures authentication settings. ## Basic Initialization ### CDN Method (Recommended) ```javascript // Initialize with minimal configuration const memberstack = window.MemberstackDom.init({ publicKey: 'pk_sb_your-public-key-here' }); // The instance is now available globally console.log(window.$memberstackDom); // Same as memberstack variable ``` ### NPM/ES Module Method ```javascript import MemberstackDom from '@memberstack/dom'; const memberstack = MemberstackDom.init({ publicKey: 'pk_sb_your-public-key-here' }); export default memberstack; ``` ## Configuration Options ### Complete Configuration Interface ```typescript interface DOMConfig { publicKey: string; // Required: Your Memberstack public key appId?: string; // Optional: Specific app ID useCookies?: boolean; // Optional: Enable cookie storage (default: false) setCookieOnRootDomain?: boolean; // Optional: Set cookies on root domain (default: false) domain?: string; // Optional: Custom API domain } ``` ### Configuration Examples #### Production Configuration ```javascript const memberstack = window.MemberstackDom.init({ publicKey: 'pk_prod_your-production-key', useCookies: true, setCookieOnRootDomain: true }); ``` #### Development Configuration ```javascript const memberstack = window.MemberstackDom.init({ publicKey: 'pk_sb_your-sandbox-key', useCookies: true, domain: 'https://api-dev.memberstack.com' // Custom endpoint }); ``` #### Multi-App Configuration ```javascript const memberstack = window.MemberstackDom.init({ publicKey: 'pk_sb_your-key', appId: 'app_specific_id_here', useCookies: true }); ``` ## Configuration Details ### publicKey (Required) Your Memberstack public key from the dashboard. ```javascript // Sandbox key format publicKey: 'pk_sb_1234567890abcdef' // Production key format publicKey: 'pk_prod_1234567890abcdef' ``` **Finding Your Public Key:** 1. Login to Memberstack Dashboard 2. Go to Settings → API Keys 3. Copy the "Public Key" (starts with `pk_`) ### useCookies (Recommended: true) Enables cookie-based authentication storage for better cross-tab sync. ```javascript // Enable cookies (recommended for web apps) const memberstack = window.MemberstackDom.init({ publicKey: 'pk_sb_your-key', useCookies: true }); ``` **Benefits of cookies:** - Automatic authentication across browser tabs - Persistent login across browser sessions - Better security than localStorage for tokens ### setCookieOnRootDomain Sets authentication cookies on the root domain for subdomain sharing. ```javascript // For apps with multiple subdomains (app.example.com, api.example.com) const memberstack = window.MemberstackDom.init({ publicKey: 'pk_sb_your-key', useCookies: true, setCookieOnRootDomain: true // Cookies work across *.example.com }); ``` ### domain (Custom API Endpoint) Override the default API endpoint for development or custom deployments. ```javascript // Development environment const memberstack = window.MemberstackDom.init({ publicKey: 'pk_sb_your-key', domain: 'https://api-dev.memberstack.com' }); // Custom endpoint const memberstack = window.MemberstackDom.init({ publicKey: 'pk_sb_your-key', domain: 'https://your-custom-api.com' }); ``` ## Initialization Patterns ### Basic Web App ```html <!DOCTYPE html> <html> <head> <title>My App</title> </head> <body> <script src="https://api.memberstack.com/static/memberstack-dom.js"></script> <script> // Initialize on page load document.addEventListener('DOMContentLoaded', function() { const memberstack = window.MemberstackDom.init({ publicKey: 'pk_sb_your-key', useCookies: true }); // Setup auth state listener memberstack.onAuthChange(({ member }) => { console.log('Auth state changed:', member ? 'logged in' : 'logged out'); }); }); </script> </body> </html> ``` ### React App ```jsx // services/memberstack.js import MemberstackDom from '@memberstack/dom'; let memberstack = null; export const initMemberstack = () => { if (!memberstack) { memberstack = MemberstackDom.init({ publicKey: process.env.REACT_APP_MEMBERSTACK_PUBLIC_KEY, useCookies: true }); } return memberstack; }; export const getMemberstack = () => { if (!memberstack) { throw new Error('Memberstack not initialized. Call initMemberstack() first.'); } return memberstack; }; // App.jsx import { useEffect } from 'react'; import { initMemberstack } from './services/memberstack'; function App() { useEffect(() => { const memberstack = initMemberstack(); memberstack.onAuthChange(({ member }) => { // Handle auth state changes console.log('Member:', member); }); }, []); return <div>My App</div>; } ``` ### Next.js App ```javascript // lib/memberstack.js import MemberstackDom from '@memberstack/dom'; let memberstack = null; export const initMemberstack = () => { // Only initialize in browser environment if (typeof window !== 'undefined' && !memberstack) { memberstack = MemberstackDom.init({ publicKey: process.env.NEXT_PUBLIC_MEMBERSTACK_PUBLIC_KEY, useCookies: true }); } return memberstack; }; // pages/_app.js import { useEffect } from 'react'; import { initMemberstack } from '../lib/memberstack'; function MyApp({ Component, pageProps }) { useEffect(() => { initMemberstack(); }, []); return <Component {...pageProps} />; } ``` ### Vue.js App ```javascript // plugins/memberstack.js import MemberstackDom from '@memberstack/dom'; let memberstack = null; export const initMemberstack = () => { if (!memberstack) { memberstack = MemberstackDom.init({ publicKey: process.env.VUE_APP_MEMBERSTACK_PUBLIC_KEY, useCookies: true }); } return memberstack; }; // main.js import { createApp } from 'vue'; import App from './App.vue'; import { initMemberstack } from './plugins/memberstack'; const app = createApp(App); // Initialize Memberstack initMemberstack(); app.mount('#app'); ``` ## Environment Configuration ### Environment Variables Store your public keys in environment variables: ```bash # .env file MEMBERSTACK_PUBLIC_KEY_SANDBOX=pk_sb_your-sandbox-key MEMBERSTACK_PUBLIC_KEY_PRODUCTION=pk_prod_your-production-key ``` ```javascript // Environment-based initialization const memberstack = window.MemberstackDom.init({ publicKey: process.env.NODE_ENV === 'production' ? process.env.MEMBERSTACK_PUBLIC_KEY_PRODUCTION : process.env.MEMBERSTACK_PUBLIC_KEY_SANDBOX, useCookies: true }); ``` ### Multi-Environment Setup ```javascript const environments = { development: { publicKey: 'pk_sb_dev-key', domain: 'https://api-dev.memberstack.com' }, staging: { publicKey: 'pk_sb_staging-key', domain: 'https://api-staging.memberstack.com' }, production: { publicKey: 'pk_prod_production-key' } }; const config = environments[process.env.NODE_ENV] || environments.development; const memberstack = window.MemberstackDom.init({ ...config, useCookies: true }); ``` ## Error Handling ### Initialization Error Handling ```javascript try { const memberstack = window.MemberstackDom.init({ publicKey: 'pk_sb_your-key', useCookies: true }); console.log('Memberstack initialized successfully'); } catch (error) { console.error('Memberstack initialization failed:', error); // Handle specific errors if (error.message.includes('Invalid public key')) { alert('Configuration error: Invalid Memberstack public key'); } else { alert('Failed to initialize authentication system'); } } ``` ### Async Initialization Check ```javascript const memberstack = window.MemberstackDom.init({ publicKey: 'pk_sb_your-key', useCookies: true }); // Wait for initialization to complete async function waitForMemberstack() { let retries = 0; const maxRetries = 10; while (!window.$memberstackDom && retries < maxRetries) { await new Promise(resolve => setTimeout(resolve, 100)); retries++; } if (!window.$memberstackDom) { throw new Error('Memberstack initialization timeout'); } return window.$memberstackDom; } // Usage try { const memberstack = await waitForMemberstack(); console.log('Memberstack ready:', memberstack); } catch (error) { console.error('Memberstack initialization failed:', error); } ``` ## Validation & Testing ### Check Initialization Success ```javascript function validateMemberstackInit() { // Check global instance exists if (!window.$memberstackDom) { throw new Error('Memberstack not initialized'); } // Check required methods exist const requiredMethods = [ 'loginMemberEmailPassword', 'getCurrentMember', 'logout', 'onAuthChange' ]; for (const method of requiredMethods) { if (typeof window.$memberstackDom[method] !== 'function') { throw new Error(`Memberstack method ${method} not available`); } } console.log('✅ Memberstack validation passed'); return true; } // Run validation after init const memberstack = window.MemberstackDom.init({ publicKey: 'pk_sb_your-key', useCookies: true }); try { validateMemberstackInit(); } catch (error) { console.error('❌ Memberstack validation failed:', error); } ``` ### Test Connection ```javascript async function testMemberstackConnection() { try { // Test with a simple API call const result = await window.$memberstackDom.getApp(); console.log('✅ Connection test passed:', result.data.name); return true; } catch (error) { console.error('❌ Connection test failed:', error.message); return false; } } // Run connection test testMemberstackConnection(); ``` ## Troubleshooting ### Common Issues **"Memberstack is not defined"** ```javascript // ❌ Wrong - Memberstack not loaded yet const memberstack = window.MemberstackDom.init({ ... }); // ✅ Correct - Wait for script to load document.addEventListener('DOMContentLoaded', function() { const memberstack = window.MemberstackDom.init({ ... }); }); ``` **"Invalid public key"** ```javascript // ❌ Wrong - Missing pk_ prefix publicKey: 'sb_1234567890abcdef' // ✅ Correct - Include full key publicKey: 'pk_sb_1234567890abcdef' ``` **Cookies not working across subdomains** ```javascript // ❌ Wrong - Root domain not enabled useCookies: true // ✅ Correct - Enable root domain cookies useCookies: true, setCookieOnRootDomain: true ``` ## Next Steps - **[02-authentication.md](02-authentication.md)** - Authentication methods after initialization - **[06-member-journey.md](06-member-journey.md)** - Setting up authentication state listeners - **[09-error-handling.md](09-error-handling.md)** - Comprehensive error handling - **[10-examples.md](10-examples.md)** - Complete app examples with initialization