Custom Settings

Advanced language-specific and compiler configuration options

Custom settings provide fine-grained control over language compilers, template engines, module resolution, and other advanced features in LiveCodes.

Overview

The customSettings property in the Config object allows you to configure:

• Language-specific compiler options
• CSS processor settings
• Template engine behavior
• Module resolution and import mapping
• Script loading behavior
• CDN preferences

const config = {
  customSettings: {
    // Language-specific settings
    typescript: { /* TS compiler options */ },
    tailwindcss: { /* Tailwind config */ },
    
    // Global settings
    template: { /* template settings */ },
    imports: { /* import maps */ },
    mapImports: true,
    defaultCDN: 'jsdelivr',
  },
};

Template Settings

customSettings.template · object

Configure template engine behavior.

customSettings.template.data · any

Data object passed to template engines.

Available in templates like Handlebars, EJS, Nunjucks, Liquid, etc.

customSettings: {
  template: {
    data: {
      title: 'My Page',
      items: ['Item 1', 'Item 2', 'Item 3'],
    },
  },
}

Then in a Handlebars template:

<h1>{{title}}</h1>
<ul>
  {{#each items}}
    <li>{{this}}</li>
  {{/each}}
</ul>

customSettings.template.prerender · boolean

If false, disables pre-rendering for template languages.

By default, templates are rendered at compile time. Set to false to render at runtime.

customSettings: {
  template: {
    prerender: false,
  },
}

Script Loading

customSettings.scriptType · string

Specifies the script type attribute for the compiled script.

Available values:

• "module" (default for most languages)
• "application/javascript"
• "application/ecmascript"
• "text/javascript"
• "text/ecmascript"
• "" (no type attribute)

customSettings: {
  scriptType: 'module',
}

Module Resolution

customSettings.mapImports · boolean

Enable automatic import mapping for bare module specifiers.

When true, bare imports like import React from 'react' are automatically resolved using the configured CDN.

customSettings: {
  mapImports: true,
}

customSettings.imports · Record<string, string>

Custom import maps for module resolution.

This is similar to the top-level imports config property but scoped to custom settings.

customSettings: {
  imports: {
    'lodash': 'https://cdn.jsdelivr.net/npm/lodash-es@4/+esm',
    'date-fns': 'https://esm.sh/date-fns@3',
  },
}

customSettings.convertCommonjs · boolean

Automatically convert CommonJS modules to ES modules.

Useful when importing packages that use require() and module.exports.

customSettings: {
  convertCommonjs: true,
}

customSettings.defaultCDN · CDN

Sets the default CDN for resolving bare module imports.

Available CDNs:

• "jspm"
• "skypack"
• "jsdelivr" (default)
• "fastly.jsdelivr"
• "gcore.jsdelivr"
• "jsdelivr.esm"
• "esm.run"
• "esm.sh"
• "esbuild"
• "bundle.run"
• "unpkg"
• "statically"

customSettings: {
  defaultCDN: 'esm.sh',
}

customSettings.types · Types

Custom TypeScript type declarations for IntelliSense.

Same as the top-level types property but scoped to custom settings.

customSettings: {
  types: {
    'my-custom-lib': 'https://example.com/types.d.ts',
  },
}

Language-Specific Settings

Each language can have its own custom settings object. The structure depends on the language compiler.

TypeScript

customSettings: {
  typescript: {
    // TypeScript compiler options
    target: 'ES2020',
    jsx: 'react',
    strict: true,
    esModuleInterop: true,
  },
}

Babel

customSettings: {
  babel: {
    presets: ['@babel/preset-env', '@babel/preset-react'],
    plugins: ['@babel/plugin-proposal-class-properties'],
  },
}

Python (Pyodide)

customSettings: {
  python: {
    packages: ['numpy', 'matplotlib'],
  },
}

Tailwind CSS

customSettings: {
  tailwindcss: {
    theme: {
      extend: {
        colors: {
          primary: '#3B82F6',
        },
      },
    },
  },
}

PostCSS

customSettings: {
  postcss: {
    plugins: {
      'postcss-nested': {},
      'postcss-custom-properties': {},
    },
  },
}

UnoCSS

customSettings: {
  unocss: {
    presets: ['uno', 'attributify', 'icons'],
    theme: {
      colors: {
        primary: '#3B82F6',
      },
    },
  },
}

Vue

customSettings: {
  vue: {
    version: '3',
  },
}

Svelte

customSettings: {
  svelte: {
    compilerOptions: {
      css: true,
      dev: false,
    },
  },
}

Solid

customSettings: {
  solid: {
    generate: 'dom', // or 'ssr'
    hydratable: false,
  },
}

Complete Examples

React with TypeScript and Tailwind

import { createPlayground } from 'livecodes';

const config = {
  script: {
    language: 'tsx',
    content: `
import { createRoot } from 'react-dom/client';

function App() {
  return (
    <div className="p-4">
      <h1 className="text-4xl font-bold text-primary">Hello!</h1>
    </div>
  );
}

createRoot(document.getElementById('root')!).render(<App />);
    `,
  },
  style: {
    language: 'css',
    content: '@tailwind base; @tailwind components; @tailwind utilities;',
  },
  markup: {
    language: 'html',
    content: '<div id="root"></div>',
  },
  processors: ['tailwindcss'],
  customSettings: {
    // TypeScript compiler options
    typescript: {
      target: 'ES2020',
      jsx: 'react-jsx',
      strict: true,
    },
    // Tailwind configuration
    tailwindcss: {
      theme: {
        extend: {
          colors: {
            primary: '#3B82F6',
          },
        },
      },
    },
    // Import mapping
    imports: {
      'react': 'https://esm.sh/react@18',
      'react-dom/client': 'https://esm.sh/react-dom@18/client',
    },
  },
};

await createPlayground('#container', { config });

Template with Data

const config = {
  markup: {
    language: 'handlebars',
    content: `
<div class="container">
  <h1>{{title}}</h1>
  <ul>
    {{#each items}}
      <li>{{name}} - ${{price}}</li>
    {{/each}}
  </ul>
  <p>Total: ${{total}}</p>
</div>
    `,
  },
  customSettings: {
    template: {
      data: {
        title: 'Shopping Cart',
        items: [
          { name: 'Item 1', price: 10 },
          { name: 'Item 2', price: 20 },
          { name: 'Item 3', price: 30 },
        ],
        total: 60,
      },
    },
  },
};

await createPlayground('#container', { config });

Custom CDN and Module Resolution

const config = {
  script: {
    language: 'javascript',
    content: `
import { format } from 'date-fns';
import _ from 'lodash-es';

const now = new Date();
console.log(format(now, 'PPpp'));
console.log(_.chunk([1, 2, 3, 4, 5], 2));
    `,
  },
  customSettings: {
    // Use esm.sh as default CDN
    defaultCDN: 'esm.sh',
    
    // Enable auto import mapping
    mapImports: true,
    
    // Custom import maps for specific packages
    imports: {
      'lodash-es': 'https://cdn.jsdelivr.net/npm/lodash-es@4/+esm',
    },
  },
};

await createPlayground('#container', { config });

Python with Packages

const config = {
  script: {
    language: 'python',
    content: `
import numpy as np
import matplotlib.pyplot as plt

x = np.linspace(0, 10, 100)
y = np.sin(x)

plt.plot(x, y)
plt.title('Sine Wave')
plt.show()
    `,
  },
  customSettings: {
    python: {
      packages: ['numpy', 'matplotlib'],
    },
  },
};

await createPlayground('#container', { config });

Setting via URL Parameters

Custom settings can be configured via URL parameters using dot notation:

https://livecodes.io/
  ?customSettings.template.prerender=false
  &customSettings.defaultCDN=esm.sh
  &customSettings.mapImports=true

Or as JSON:

https://livecodes.io/
  ?customSettings={"template":{"prerender":false},"defaultCDN":"esm.sh"}

Runtime Configuration

Custom settings can be modified at runtime:

const playground = await createPlayground('#container');

// Update custom settings
await playground.setConfig({
  customSettings: {
    tailwindcss: {
      theme: {
        extend: {
          colors: {
            accent: '#10B981',
          },
        },
      },
    },
  },
});

Language Documentation

For detailed language-specific compiler options, refer to the individual language documentation:

TypeScript

TypeScript compiler options

Tailwind CSS

Tailwind configuration

PostCSS

PostCSS plugins and settings

Python

Python package configuration

Best Practices

Use Type Definitions

When working with TypeScript, provide custom type definitions in customSettings.types for better IntelliSense support.

Minimize Package Imports

Only load necessary packages to keep bundle size small and improve load times.

CDN Selection

Choose a CDN based on your needs:

• esm.sh: Automatic TypeScript types, good for development
• jsdelivr: Fast, reliable, good for production
• skypack: Optimized builds, good balance

Template Data Validation

Validate template data to prevent runtime errors in template rendering.

Related Documentation

Configuration Object

Complete Config reference

Module Resolution

Learn about module imports and CDNs

Languages

Supported languages and their options

CSS Processors

CSS processor configuration