electron / electron/website

[Feature Request]: Interactive API Playground for Documentation

Open
#985 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
157
Forks
207
Avg merge
4h 57m
Merged PRs (30d)
20

Description

## Summary

Add an interactive code playground to the Electron documentation that allows users to experiment with Electron APIs directly in the browser, similar to how React, Vue, and Svelte offer live playgrounds.

## Problem

Currently, users reading the Electron API documentation encounter static code examples. To test or experiment with these examples, they must:

1. Set up a local Electron development environment, or
2. Install and open Electron Fiddle separately

This friction reduces learning efficiency and makes the documentation less accessible to newcomers exploring Electron for the first time.

## Proposed Solution

Create an **Interactive API Playground** component that can be embedded within documentation pages, featuring:

### Core Features

- **Live Code Editor**: Embedded Monaco Editor or CodeMirror with syntax highlighting and autocomplete
- **Split View**: Code editor + output preview panel
- **Preset Examples**: Pre-populated code snippets for each API (main process, renderer process, preload scripts)
- **"Open in Fiddle" Button**: One-click export to Electron Fiddle for full-featured testing

### Technical Approach

```
┌─────────────────────────────────────────────────────────────┐
│ Interactive API Playground │
├─────────────────────────────────────────────────────────────┤
│ ┌─────────────────────┐ ┌───────────────────────────────┐ │
│ │ main.js │ │ Simulated Output │ │
│ │ ─────────────────│ │ ─────────────────────────── │ │
│ │ const { app } = │ │ ✓ app ready │ │
│ │ require('...') │ │ ✓ window created │ │
│ │ ... │ │ ► Console logs appear here │ │
│ └─────────────────────┘ └───────────────────────────────┘ │
│ [▶ Run] [Reset] [Open in Fiddle] [Copy Code] │
├─────────────────────────────────────────────────────────────┤
│ Tabs: main.js | preload.js | renderer.js | index.html │
└─────────────────────────────────────────────────────────────┘
```

### Implementation Considerations

1. **Client-Side Only**: Since Electron requires Node.js APIs, the playground would simulate outputs for common API patterns (dialog boxes, notifications, etc.) or use a WebSocket connection to a sandboxed backend.

2. **Electron Fiddle Integration**: Leverage [Fiddle's Gist export format](https://github.com/electron/fiddle) to enable seamless "Open in Fiddle" functionality.

3. **Progressive Enhancement**: Show static code blocks by default, with playground enhancement for supported browsers/contexts.

4. **Docusaurus Plugin**: Build as a custom Docusaurus plugin/component that can be used via MDX:
```mdx

```

## Benefits

- **Lower barrier to entry** for developers new to Electron
- **Faster learning** through hands-on experimentation
- **Better documentation engagement** (users spend more time learning)
- **Complementary to Electron Fiddle** rather than replacing it

## Prior Art

- [Svelte REPL](https://svelte.dev/repl)
- [Vue SFC Playground](https://play.vuejs.org/)
- [React CodeSandbox embeds](https://codesandbox.io/)
- [TypeScript Playground](https://www.typescriptlang.org/play)

## Potential Challenges

1. **Electron APIs require Node.js**: Simulating system dialogs, file system access, etc. in browser context requires creative solutions (mock responses, screenshots, video demos)
2. **Bundle size**: Monaco Editor is large; need to consider lazy loading
3. **Security**: If implementing a sandboxed execution environment, careful security review is essential

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.