How paranext/paranext-extension-template works
Project Type and Purpose
• This is neither a web server nor a microservice‐based system, but an extension template for the Platform.Bible desktop application.
• It provides the skeleton for:
• an extension “main” process (TypeScript code registered via the PAPI)
• optional React‐based WebViews
• asset and contribution metadata
• build & packaging pipelines
File Structure
• src/ (entry point src/main.ts, .web-view.tsx React UIs, type definitions)
• contributions/ (menus, settings, themes JSON)
• lib/ (helper scripts for version bumping, Git utilities)
• webpack/ (multiple Webpack configs & a custom plugin for resolving WebViews)
• root configs: package.json, manifest.json, TypeScript, Tailwind, PostCSS, ESLint, Stylelint
• CI: .github/workflows/publish.yml for releases
Core Components
a. Source Code & Metadata
• src/ (main.ts + WebView code + types)
• assets/ (images, localized descriptions)
• contributions/ JSON definitions
• manifest.json & package.json (extension identity, dependencies)
b. Build System
• Webpack with three configurations:
• Main process bundle (webpack.config.main.ts)
• Web‐View bundles (webpack.config.web-view.ts)
• Shared/base config (webpack.config.base.ts)
• SWC‐loader for TS→JS
• PostCSS & Tailwind for styling
• Custom plugin web-view-resolve-webpack-plugin
• lib scripts (bump-versions.ts, git.util.ts) invoked by npm scripts
c. Continuous Integration / Release Pipeline
• GitHub Actions (publish.yml)
• npm scripts: build, watch, package, bump-versions
• Output artifacts: dist/ folder, zipped release/
d. Runtime / Host Integration
• Platform.Bible desktop application
• Extension Loader reads manifest.json and dist/
• PAPI (Platform API) bridges main.ts commands into host
• WebViews loaded via papi-extension: protocol
• Contributions modify host menus, settings, themes
Relationships & Data Flow
• Developer writes code/assets → commits to Git
↓
• npm scripts trigger Webpack + PostCSS + Tailwind → produce bundles in dist/
↓
• GitHub Actions (on release) call npm run package → zip + GitHub Release
↓
• Platform.Bible (runtime) loads extension from dist/:
• Registers commands/events via PAPI
• Renders UI in host windows or WebViews
• Applies contributions/ JSON to host menus/settings
Architectural Patterns & Design Principles
• Separation of Concerns:
• Main (“backend”) vs. WebView (“frontend”) code
• Static assets & metadata vs. runtime logic
• Plugin‐style extension:
• Manifest-driven contributions
• Host‐plugin interface via PAPI
• Modular bundling:
• Multiple Webpack entries/configs
• Shared base config for consistency
Final Checklist
• Components: source modules, assets, webpack configs, CI, host
• Data flows: code → build → dist → runtime
• Architectural annotations: plugin‐style, separation of main vs. UI