MagicDX

Theme

Installation Guide ​

Detailed installation instructions for all MagicDX plugins.

📋 Prerequisites ​

System Requirements ​

RequirementVersion
Node.js18.x, 20.x, 22.x
Strapiv5.0.0+
npm8.x+ or yarn 1.22+

Database Support ​

All MagicDX plugins support:

  • ✅ SQLite
  • ✅ PostgreSQL
  • ✅ MySQL
  • ✅ MariaDB

Magic-Mail Installation ​

1. Install Package ​

bash
npm install strapi-plugin-magic-mail
# or
yarn add strapi-plugin-magic-mail

2. Configure Plugin ​

Create or update config/plugins.ts:

typescript
export default () => ({
  'magic-mail': {
    enabled: true,
    // Optional: Advanced configuration
    config: {
      // No additional config needed - everything is managed in admin panel
    },
  },
});

3. Build & Start ​

bash
npm run build
npm run develop

4. Set Up Email Provider ​

  1. Go to Admin → MagicMail → Email Accounts
  2. Click "Add Account"
  3. Choose provider (Gmail OAuth, SMTP, SendGrid, etc.)
  4. Enter credentials
  5. Test connection
  6. Done!

Dependencies ​

Magic-Mail has no additional dependencies. It optionally integrates with:

  • strapi-plugin-email-designer-5 for visual email design

1. Install Package ​

bash
npm install strapi-plugin-magic-link-v5
# or
yarn add strapi-plugin-magic-link-v5

2. Configure Plugin ​

typescript
export default () => ({
  'magic-link': {
    enabled: true,
  },
});

3. Email Provider Required ​

Magic-Link requires an email provider. Choose one:

Option A: Use Magic-Mail (Recommended)

typescript
export default () => ({
  'magic-mail': { enabled: true },
  'magic-link': { enabled: true },
});

Option B: Use Strapi Email Plugin

bash
npm install @strapi/provider-email-nodemailer
typescript
// config/plugins.ts
export default () => ({
  email: {
    config: {
      provider: 'nodemailer',
      providerOptions: {
        host: process.env.SMTP_HOST,
        port: process.env.SMTP_PORT,
        auth: {
          user: process.env.SMTP_USER,
          pass: process.env.SMTP_PASSWORD,
        },
      },
    },
  },
  'magic-link': { enabled: true },
});

4. Build & Start ​

bash
npm run build
npm run develop

5. Activate License ​

  1. Go to Admin → Magic-Link
  2. Click "Activate License"
  3. Enter details or license key
  4. Configure settings

Magic-Sessionmanager Installation ​

1. Install Package ​

bash
npm install strapi-plugin-magic-sessionmanager
# or
yarn add strapi-plugin-magic-sessionmanager

2. Configure Plugin ​

typescript
export default () => ({
  'magic-sessionmanager': {
    enabled: true,
    config: {
      // Optional configuration
      lastSeenRateLimit: 30000,    // Update interval (ms)
      inactivityTimeout: 900000,   // Inactive after 15 min
    },
  },
});

3. Build & Start ​

bash
npm run build
npm run develop

4. Optional: Encryption Key ​

For enhanced security, add to .env:

bash
SESSION_ENCRYPTION_KEY=your-32-byte-base64-key

Generate a key:

bash
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Or generate in admin: Sessions → Settings → Generate Key

Magic-Mark Installation ​

1. Install Package ​

bash
npm install strapi-plugin-magic-mark
# or
yarn add strapi-plugin-magic-mark

2. Configure Plugin ​

typescript
export default () => ({
  'magic-mark': {
    enabled: true,
    config: {
      // Optional configuration
      maxBookmarksPerUser: 50,
      enableHistory: true,
    },
  },
});

3. Build & Start ​

bash
npm run build
npm run develop

4. Start Using ​

  1. Navigate to any Content Manager collection
  2. Apply filters/sorting
  3. Click the MagicMark button in toolbar
  4. Save bookmark!

🔌 Installing All Plugins ​

For the complete MagicDX experience:

1. Install All ​

bash
npm install strapi-plugin-magic-mail strapi-plugin-magic-link-v5 strapi-plugin-magic-sessionmanager strapi-plugin-magic-mark

2. Configure All ​

typescript
// config/plugins.ts
export default () => ({
  // Email management
  'magic-mail': {
    enabled: true,
  },
  
  // Passwordless authentication
  'magic-link': {
    enabled: true,
  },
  
  // Session tracking
  'magic-sessionmanager': {
    enabled: true,
  },
  
  // Query bookmarks
  'magic-mark': {
    enabled: true,
  },
});

3. Build & Start ​

bash
npm run build
npm run develop

4. Activate Each Plugin ​

Visit each plugin in admin and activate the license.

Troubleshooting Installation ​

Plugin Not Appearing ​

bash
# Clear cache and rebuild
rm -rf .cache node_modules/.cache
npm run build
npm run develop

Database Migration Errors ​

bash
# Reset database (development only!)
rm -rf .tmp
npm run develop

Peer Dependency Warnings ​

bash
# If you see peer dependency warnings
npm install --legacy-peer-deps

TypeScript Errors ​

Ensure your tsconfig.json includes:

json
{
  "compilerOptions": {
    "module": "CommonJS",
    "moduleResolution": "node"
  }
}

📖 Next Steps ​