Syncfusion React License

Syncfusion React Licensing

This skill guides you through Syncfusion React licensing requirements, license key generation, registration methods, and troubleshooting validation errors.

Table of Contents

• Licensing Overview
• Documentation and Navigation Guide
• Quick Start
• Common Registration Methods

Licensing Overview

Syncfusion license key validation was introduced in the 2022 Volume 1 release (v20.1.0.47) for Essential JS2 platforms. All React applications referencing Syncfusion packages from npm, CDN, or build must register a valid license key to avoid validation warnings.

Key Licensing Details

License Key vs Unlock Key:

• License Key: String registered in application code to validate Syncfusion package usage
• Unlock Key: Used only during Syncfusion installer process
• ⚠️ Important: License key is NOT the same as installer unlock key

Core Requirements:

• License key validation introduced in v20.1.0.47+ (2022 Volume 1)
• License keys are version and platform/edition specific
• Validation occurs offline (no internet required during runtime)
• Required when using npm packages or trial installers
• Not required when using licensed installers

License Types:

• Trial license: 30-day evaluation period, full functionality, generates trial key, displays warning after expiration
• Community license: Free for qualifying individuals/organizations (<$1M USD revenue), same functionality as paid license, annual renewal required
• Paid license: Commercial license for enterprise use, perpetual or subscription-based, technical support included

Edition-Based vs Platform-Based:

• v31.1.17+ (Edition-based): UI Edition, Document SDK, PDF Viewer SDK, DOCX Editor SDK, Spreadsheet Editor SDK, Enterprise Edition (all editions combined)
• v30.x.x and earlier (Platform-based): React, Angular, Vue, JavaScript, Blazor, etc.

Build Server Scenarios:

• Using npm packages: License key required - register NPX command
• Using trial installer: License key required - trial warnings appear after 30 days
• Using licensed installer: License key NOT required - embedded license validation included

Offline Validation:

• No internet connection required during application runtime
• License validated locally against package metadata at startup
• Works in air-gapped environments and offline development
• No external API calls or performance impact

Documentation and Navigation Guide

Generating License Keys

📄 Read: references/license-generation.md

• Edition-based licensing (v31.1.17+): UI Edition, Document SDK, PDF Viewer SDK, DOCX Editor SDK, Spreadsheet Editor SDK, Enterprise Edition
• Platform-based licensing (v30.x.x and earlier): React, JavaScript, Angular, etc.
• Generating keys from License & Downloads page
• Claim License Key page usage
• Version and platform specific license key

Registering License Keys

📄 Read: references/license-registration.md

• Environment variable method: SYNCFUSION_LICENSE
• CI/CD integration: GitHub Actions, Azure Pipelines
• Active license, active trial, expired license scenarios

Troubleshooting License Errors

📄 Read: references/licensing-errors.md

• License key not registered error
• Invalid key error
• Trial expired error (30 days)
• Platform mismatch error
• Version mismatch error
• NPX command validation errors

Quick Start

1. Generate License Key

Visit License & Downloads page:

For v31.1.17+ (Edition-based):

• Select version 31.x.x or higher
• Select required editions: UI Edition, Document SDK, PDF Viewer SDK, DOCX Editor SDK, Spreadsheet Editor SDK
• Recommended: Select all 5 editions for Enterprise Edition key
• Click "Get License Key"

For v30.x.x and earlier (Platform-based):

• Select version 30.x.x or earlier
• Select platforms: React, JavaScript, etc.
• Click "Get License Key"

2. Register License Key in Application

Recommended Method: Use environment variables to register your license key. This prevents accidentally committing license keys to source control.

Step 1: Set the environment variable:

# Windows
setx SYNCFUSION_LICENSE "Your_License_Key_Here"

# Mac/Linux
export SYNCFUSION_LICENSE='Your_License_Key_Here'

Step 2: Activate the license using NPX command:

npx syncfusion-license activate

Step 3: Clear the cache:

# Windows PowerShell
Remove-Item -Recurse -Force node_modules\.cache

# macOS/Linux
rm -rf node_modules/.cache

Note: For alternative license registration methods, kindly refer to the Syncfusion license key registration documentation.

License Key Generation

Table of Contents

• Overview
• Edition-Based Licensing (v31.1.17+)
• Platform-Based Licensing (v30.x.x and Earlier)
• Alternative: Claim License Key Page

Overview

Generate Syncfusion license keys from your account portal:

• License & Downloads - For paid licenses
• Trial & Downloads - For trial licenses

The generation process differs based on version:

• v31.1.17+ (2025 Volume 3+): Edition-based licensing
• v30.x.x and earlier: Platform-based licensing

Edition-Based Licensing (v31.1.17+)

Starting with Essential Studio v31.1.17 (2025 Volume 3), Syncfusion moved to edition-based licensing for simpler license management across platforms.

Available Editions

Steps to Generate License Key

Step 1: Navigate to Downloads and Keys

Step 2: Click "Get License Key" button

Step 3: Select version 31.x.x or higher from dropdown

Step 4: Select required edition(s) from dropdown menu

For Enterprise Edition key (Recommended): Select all 5 options:

• ✅ UI Edition
• ✅ Document SDK
• ✅ DOCX Editor SDK
• ✅ PDF Viewer SDK
• ✅ Spreadsheet Editor SDK

Step 5: Click "Get License Key"

Result: Your license key is generated and displayed on screen

Platform-Based Licensing (v30.x.x and Earlier)

For Syncfusion versions 30.x.x and earlier, license keys are generated per platform.

Steps to Generate License Key

Step 1: Navigate to Downloads and Keys

Step 2: Click "Get License Key" button

Step 3: Select version 30.x.x or earlier from dropdown

Step 4: Select platform(s) from dropdown menu

Available platforms:

• React
• JavaScript
• Angular
• Vue
• Blazor
• ASP.NET Core
• ASP.NET MVC
• WPF
• WinForms
• Xamarin
• .NET MAUI

You can select multiple platforms:

Step 5: Click "Get License Key"

Result: Platform-specific license key generated

Alternative: Claim License Key Page

Alternative method to generate license keys based on your account status.

Accessing Claim License Key

Navigate to Claim License Key page.

The page automatically detects your account status and provides appropriate options.

Active License

Status: Valid paid or community license

Action: Click "Claim License Key" to generate key immediately

Key characteristics:

• Valid for license duration
• No expiration warnings
• Full access to all licensed features

Active Trial

Status: Valid 30-day trial active on account

Action: Click "Claim Trial License Key" to generate trial key

Key characteristics:

• Valid for 30 days from trial start date
• Expiration date displayed
• Full functionality during trial period
• License warning appears after expiration

Expired License

Status: License subscription has expired

Action: Temporary 5-day license key generated

To resolve: 1. Renew license subscription 2. Generate new license key 3. Register new key in application

No Trial or License

Status: Account has no active trial or license

Options:

• Click "Start Trial" → Generates 30-day trial license key
• Click "Purchase" → Redirects to sales page

License Key Registration

Table of Contents

• Overview
• Register License with Environment Variables
• CI/CD Integration

Overview

The generated Syncfusion license key must be registered in your React application. The recommended approach is to use environment variables to avoid accidentally committing license keys to source control.

Important Notes:

• License validation is performed offline during application execution
• No internet connection required after registration
• Apps can be deployed on any system without internet access
• License key registration required from v20.1.0.47+ (2022 Volume 1) onwards

Register License with Environment Variables

The recommended way to register your Syncfusion license key is using environment variables. This approach keeps your license key secure and prevents accidental commits to source control.

Step 1: Set Environment Variable

Set the SYNCFUSION_LICENSE environment variable on your system with your license key.

Windows

Open command prompt and use the setx command:

setx SYNCFUSION_LICENSE "Your_License_Key_Here"

Mac

Open terminal and add to your bash profile:

echo 'export SYNCFUSION_LICENSE="Your_License_Key_Here"' >> ~/.bash_profile

To modify the environment variable:

nano ~/.bash_profile

Press Ctrl+X to exit, then Y and Enter to save changes.

Close and reopen terminal to see the changes using env command.

Linux

Open terminal and set the environment variable:

export SYNCFUSION_LICENSE='Your_License_Key_Here'

Step 2: Restart your IDE or terminal

After setting the environment variable, restart your IDE or application terminal.

Step 3: Activate the License

Open command prompt in the application root directory and run:

npx syncfusion-license activate

Success message:

(INFO) Syncfusion License imported successfully.

Step 4: Clear Cache

Remove the .cache folder from node_modules:

# Windows PowerShell
Remove-Item -Recurse -Force node_modules\.cache

# macOS/Linux
rm -rf node_modules/.cache

Note: For alternative license registration methods, kindly refer to the Syncfusion license key registration documentation.

CI/CD Integration

Important: Always use secret management systems in CI/CD pipelines. Never hardcode license keys in workflow files or commit them to source control.

GitHub Actions

Use environment variables in GitHub Actions to register your license in CI pipelines.

Step 1: Create a Repository Secret

1. Go to your repository → Settings → Secrets and variables → Actions 2. Click "New repository secret" 3. Name: SYNCFUSION_LICENSE 4. Value: Your license key 5. Click "Add secret"

Or create an Organization Secret to share across repositories.

Step 2: Add activation step to your workflow

# WARNING: Always use secrets, never hardcode license keys in workflow files
steps:
  - name: Install node modules
    run: npm install

  - name: Activate Syncfusion License
    run: npx syncfusion-license activate
    env:
      SYNCFUSION_LICENSE: ${{ secrets.SYNCFUSION_LICENSE }}

Complete Example:

# WARNING: Always use secrets, never hardcode license keys in workflow files
name: Build React App

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm install
      
      - name: Activate Syncfusion License
        run: npx syncfusion-license activate
        env:
          SYNCFUSION_LICENSE: ${{ secrets.SYNCFUSION_LICENSE }}
      
      - name: Build application
        run: npm run build

Azure Pipelines (YAML)

Use environment variables in Azure Pipelines to register your license.

Step 1: Create a User-defined Variable

1. Navigate to your pipeline → Edit → Variables 2. Click "New variable" 3. Name: SYNCFUSION_LICENSE 4. Value: Your license key 5. Check "Keep this value secret"

Step 2: Add activation step to your pipeline

For Windows build agents:

# WARNING: Always use secret variables, never hardcode license keys in pipeline files
pool:
  vmImage: 'windows-latest'

steps:
  - script: call npm install
    displayName: 'Install node modules'

  - script: call npx syncfusion-license activate
    displayName: 'Activate Syncfusion License'
    env:
      SYNCFUSION_LICENSE: $(SYNCFUSION_LICENSE)

For Linux build agents:

# WARNING: Always use secret variables, never hardcode license keys in pipeline files
pool:
  vmImage: 'ubuntu-latest'

steps:
  - script: npm install
    displayName: 'Install node modules'

  - script: npx syncfusion-license activate
    displayName: 'Activate Syncfusion License'
    env:
      SYNCFUSION_LICENSE: $(SYNCFUSION_LICENSE)

Azure Pipelines (Classic)

For Classic Editor users:

Step 1: Create a User-defined Variable named SYNCFUSION_LICENSE with your license key as the value. Make sure to mark it as secret.

Step 2: Add a Bash task after npm install with the following script:

# WARNING: Ensure SYNCFUSION_LICENSE is stored as a secret variable
# Never hardcode license keys in scripts
npx syncfusion-license activate

Licensing Errors and Solutions

Table of Contents

• License Key Not Registered
• Invalid License Key
• Trial License Expired
• Platform Mismatch
• Version Mismatch
• NPX Command Errors

Overview

Syncfusion licensing errors appear in browser console when license key is missing, invalid, or improperly configured. All errors are non-blocking - application continues to work normally with console warnings only.

License Key Not Registered Error

Error Message

This application was built using a trial version of Syncfusion Essential Studio.
Please include a valid license key in the application.

Cause

Syncfusion license key not registered in the application.

Solution

Generate license key from Syncfusion Portal.

Step 1: Set the environment variable:

# Windows
setx SYNCFUSION_LICENSE "Your_License_Key_Here"

# Mac/Linux
export SYNCFUSION_LICENSE='Your_License_Key_Here'

Step 2: Activate the license using NPX command:

npx syncfusion-license activate

Invalid License Key Error

Error Message

The included Syncfusion license key is invalid.

Common Causes

1. Malformed key (spaces/line breaks) 2. Wrong platform (v30.x.x and earlier) 3. Wrong version 4. Wrong edition (v31.1.17+)

Solution: Malformed Key

Key must be single line, 100-150 characters, no spaces or line breaks. Re-copy license key from portal carefully and ensure entire key is copied.

Solution: Wrong Platform (v30.x.x)

1. Go to License Portal 2. Select version 30.x.x or earlier 3. Select platform: React 4. Generate and replace key

Solution: Wrong Edition (v31.1.17+)

1. Go to License Portal 2. Select version 31.x.x or higher 3. Select all 5 editions/SDKs (UI Edition, Document SDK, DOCX Editor SDK, PDF Viewer SDK, Spreadsheet Editor SDK) 4. Generate Enterprise Edition key 5. Replace old key

Solution: Wrong Version

Check version:

npm list @syncfusion/ej2-react-grids

Generate key matching exact version from License Portal.

Trial License Expired Error

Error Message

Your Syncfusion trial license has expired.

Causes

Primary - 30-day trial period ended Secondary - configuration npm package mismatch

30-day Trial Period Solutions

Option 1: Purchase License Visit Syncfusion Sales

• Community License (Free for <$1M revenue)
• Commercial License (Paid)

Option 2: Community License Apply at Community License (approval in 1-2 days)

Option 3: Extend Trial Email support@syncfusion.com (case-by-case)

Configuration Mismatch Solutions

Explicit @syncfusion/ej2-base Dependency

Remove @syncfusion/ej2-base from package.json (auto-installed with other packages):

{
  "dependencies": {
    "@syncfusion/ej2-react-grids": "25.1.35"
    // ✅ @syncfusion/ej2-base installed automatically
  }
}

Then: Delete node_modules, package-lock.json → npm install → Clear cache

Major Version Conflict with ^ Symbol

Use ~ (tilde) instead of ^ (caret) to prevent major version upgrades:

{
  "dependencies": {
    "@syncfusion/ej2-react-grids": "~25.1.35",  // ✅ Only 25.1.x patches
    "@syncfusion/ej2-react-buttons": "~25.1.35"
  }
}

Version symbols:

• ^25.1.35 - Allows 25.x.x ❌
• ~25.1.35 - Only 25.1.x ✅
• 25.1.35 - Exact version ✅

Platform Mismatch Error

Error Message

The included Syncfusion license key is not valid for this platform.

Cause (v30.x.x and Earlier)

License key generated for one platform but used in another (e.g., Angular key in React project).

Solution

Verify platform:

cat package.json | grep "@syncfusion"
# Expected for React: "@syncfusion/ej2-react-*"

Generate correct platform key: 1. Go to License Portal 2. Select version 30.x.x or earlier 3. Select platform: React 4. Generate key

Note: For v31.1.17+, platform mismatch errors don't occur - UI Edition/Enterprise Edition keys work across all platforms.

Version Mismatch Error

Error Message

The included Syncfusion license key is not valid for version {installed_version}.

Cause

License key version doesn't match installed package version.

Solution

Step 1: Check all Syncfusion package versions

npm list | grep @syncfusion

# Expected (all same version):
# @syncfusion/ej2-react-grids@25.1.35
# @syncfusion/ej2-react-buttons@25.1.35
# @syncfusion/ej2-base@25.1.35

Step 2: Update all packages to same version if mixed

npm install @syncfusion/ej2-react-grids@26.1.35 @syncfusion/ej2-react-buttons@26.1.35

Step 3: Generate new license key for exact version from License Portal

Step 4: Clear cache

rm -rf node_modules/.cache
npm start

Version Update Workflow

# 1. Update packages
npm install @syncfusion/ej2-react-grids@26.1.35

# 2. Verify versions match
npm list | grep @syncfusion

# 3. Generate new license key for v26.1.35 from portal

# 4. Update environment variable with new key

# 5. Clear cache
rm -rf node_modules/.cache

# 6. Restart
npm start

NPX Command Errors

Error: Invalid License Key Structure

Error: Invalid license key structure.

Solution:

echo "YOUR_COMPLETE_LICENSE_KEY" > syncfusion-license.txt
npx syncfusion-license activate

Error: Version Mismatch

Error: License key version (25.1.35) does not match installed package version (26.1.35).

Solution: 1. Check version: npm list @syncfusion/ej2-base 2. Generate new key for that version 3. Update syncfusion-license.txt 4. Run: npx syncfusion-license activate

Error: Platform Mismatch

Error: License key platform (Angular) does not match detected platform (React).

Solution (v30.x.x): 1. Generate React platform key 2. Update syncfusion-license.txt 3. Run: npx syncfusion-license activate

Error: Trial License Expired

Error: Trial license has expired.

Solution: 1. Purchase or apply for community license 2. Generate new paid license key 3. Update syncfusion-license.txt 4. Run: npx syncfusion-license activate

Error: License File Not Found

Error: License file not found.

Solution Option 1:

echo "YOUR_LICENSE_KEY" > syncfusion-license.txt
npx syncfusion-license activate

Solution Option 2:

# Windows
$env:SYNCFUSION_LICENSE="YOUR_LICENSE_KEY"
npx syncfusion-license activate

# macOS/Linux
export SYNCFUSION_LICENSE="YOUR_LICENSE_KEY"
npx syncfusion-license activate