paranext-extension-template

Basic extension template for Platform.Bible

Template Info

This is a Webpack project template pre-configured to build a Platform.Bible extension. It includes only the bare essentials required for an extension to work.

Note that the *.web-view.* files and the assets folder mentioned in Summary are not included in this template. For examples of what these might look like, refer to any extension that is based on either this template or the paranext-multi-extension-template — for instance, the Text Collection extension.

Important: Before proceeding to use this template, consider whether you intend to build a single extension to be packaged and installed independently, or a set of related extensions that should be used together. If the latter, it would be better to use the template pre-configured to build an arbitrary number of Platform.Bible extensions in one repo instead of this template.

Customize extension details

Follow these instructions to customize the template to be your own Platform.Bible extension. This section is a more generalized version of the Your first extension guide, which contains step-by-step instructions to build a "Hello World" extension.

Install and hook up to the template

Note: please skip this section and continue with Replace placeholders if you are following these instructions as part of creating an extension within paranext-multi-extension-template.

To make the process of customizing from the template as smooth as possible, we recommend you do the following before anything else:

• Install and set up this repo
• Update this extension from the template to hook everything up for smooth updates in the future.

Replace placeholders

For your extension name, we recommend that you use lowerCamelCase in some contexts and kebab-case in other contexts. We generally recommend lowerCamelCase when using the name in code (like making a new command on the PAPI, for example), and we recommend kebab-case when using the name in relation to the file system, the repository, npm, and the extension's .d.ts types module. The following instructions are written accordingly.

• In this README.md:

  • Replace the first line # paranext-extension-template with # your-extension-name (kebab-case)
  • Below the first line, replace the extension description with your own description
  • In the Summary section, replace src/types/paranext-extension-template.d.ts with src/types/your-extension-name.d.ts (kebab-case)

• In manifest.json:

  • Replace paranextExtensionTemplate with yourExtensionName (lowerCamelCase)
  • Replace src/types/paranext-extension-template.d.ts with src/types/your-extension-name.d.ts (kebab-case)
  • Update ownership information and other relevant fields as desired

• In package.json:

  • Replace paranext-extension-template with your-extension-name (2 occurrences - kebab-case)
  • Update ownership information and other relevant fields as desired

• In assets/displayData.json:

  • If your extension has an icon, update the icon value to point towards the icon file (for example: assets/icon.svg)

  • Update the moreInfoUrl field to web URL to a page where users can find out more information about you / your organization / your extension.

  • Update the supportUrl field to web URL to a support page where users can request help and report issues with your extension.

  • Update the en entry of localizedDisplayInfo so that:

    • displayName contains a human-readable name for your extension (i.e. Your Extension Name).
    • shortSummary contains a short, few sentence summary of what your extension does.
    • description points to a Markdown (.md) file containing the full description of your extension (similar to what you would put in a README).

  • If your extension supports multiple languages, add another entry to localizedDisplayInfo by copying and pasting the en entry, changing en to the BCP 47 language tag of the language you want to support, and translating the displayName, shortSummary, and description fields appropriately. We recommend naming your description files description-<language tag>.md.

• In LICENSE:

  • Adjust as desired (feel free to choose a different license)
  • If you choose to stay with the current license, update the copyright statement

• Rename src/types/paranext-extension-template.d.ts to src/types/your-extension-name.d.ts (kebab-case)

  • In this renamed file, replace paranext-extension-template with your-extension-name

• In src/main.ts, replace Extension template with Your Extension Name (2 occurrences)

• In .github/assets/release-body.md, replace Extension template with Your Extension Name, and make other adjustments as desired.

Customize the extension manifest and package information

The manifest.json and package.json files contain information specific to your extension. Add your extension's details in these two files as needed. See more information on the manifest.json and package.json files in Extension Anatomy.

Hide Template Info

Once finished customizing this template to be your own, you can uncomment the HTML comment tag above the Template Info section to hide this template-related info in this readme. You can do this by clicking on the line and doing CTRL + / in VS Code. You can also do this manually by removing the first opening '<!--' and the only closing '-->' on the line. Leaving this info commented in your readme will hide it in your readme while avoiding merge conflicts if you decide to update this extension from the template in the future. If you never want to update this extension from the template, you can remove the Template Info section and sub-sections of this readme.

Note: if you update this extension from the template, there may be important changes in this section like additional customizations you must make to this extension. Please keep an eye out for readme changes when updating from the template.

Summary

The general file structure for an extension is as follows:

• package.json contains information about this extension's npm package. It is required for Platform.Bible to use the extension properly. It is copied into the build folder
• manifest.json is the manifest file that defines the extension and important properties for Platform.Bible. It is copied into the build folder
• src/ contains the source code for the extension
  • src/main.ts is the main entry file for the extension
  • src/types/paranext-extension-template.d.ts is this extension's types file that defines how other extensions can use this extension through the papi. It is copied into the build folder
  • *.web-view.tsx files will be treated as React WebViews
  • *.web-view.html files are a conventional way to provide HTML WebViews (no special functionality)
• assets/ contains asset files the extension and its WebViews can retrieve using the papi-extension: protocol, as well as textual descriptions in various languages. It is copied into the build folder
  • assets/displayData.json contains (optionally) a path to the extension's icon file as well as text for the extension's display name, short summary, and path to the full description file
  • assets/descriptions/ contains textual descriptions of the extension in various languages
    • assets/descriptions/description-<locale>.md contains a brief description of the extension in the language specified by <locale>
• contributions/ contains JSON files the platform uses to extend data structures for things like menus and settings. The JSON files are referenced from the manifest
• public/ contains other static files that are copied into the build folder
• .github/ contains files to facilitate integration with GitHub
  • .github/workflows contains GitHub Actions workflows for automating various processes in this repo
  • .github/assets/release-body.md combined with a generated changelog becomes the body of releases published using GitHub Actions
• dist/ is a generated folder containing the built extension files
• release/ is a generated folder containing a zip of the built extension files

See the Extension Anatomy wiki page for more information about the various files that comprise an extension and their relationships to each other.

To install

Install dependencies:

1. Follow the instructions to install paranext-core. We recommend you clone paranext-core in the same parent directory in which you cloned this repository so you do not have to reconfigure paths to paranext-core.
2. In this repo, run npm install to install local and published dependencies

Configure paths to paranext-core repo

If you cloned paranext-core anywhere other than in the same parent directory in which you cloned this repository, update the paths to paranext-core in this repository's package.json to point to the correct paranext-core directory.

To run

Running Platform.Bible with this extension

To run Platform.Bible with this extension:

npm start

Note: The built extension will be in the dist folder. In order for Platform.Bible to run this extension, you must provide the directory to this built extension to Platform.Bible via a command-line argument. This command-line argument is already provided in this package.json's start script. If you want to start Platform.Bible and use this extension any other way, you must provide this command-line argument or put the dist folder into Platform.Bible's extensions folder.

Building this extension independently

To watch extension files (in src) for changes:

npm run watch

To build the extension once:

npm run build

To package for distribution

To package this extension into a zip file for distribution:

npm run package

Publishing

These steps will walk you through releasing a version on GitHub and bumping the version to a new version so future changes apply to the new in-progress version.

1. Make sure the versions in this repo are on the version number you want to release. If they are not, manually dispatch the Bump Versions workflow or run the bump-versions npm script to set the versions to what you want to release on the branch you want to release from.

2. Manually dispatch the Publish workflow in GitHub Actions targeting the branch you want to release from. This workflow creates a new pre-release for the version you intend to release and creates a new bump-versions-<next_version> branch to bump the version after the release so future changes apply to a new in-progress version instead of to the already released version. This workflow has the following inputs:

   • version: Enter the version you intend to publish (e.g. 0.2.0). This is simply for verification to make sure you release the code that you intend to release. It is compared to the version in the code, and the workflow will fail if they do not match.
   • newVersionAfterPublishing: Enter the version you want to bump to after releasing (e.g. 0.3.0-alpha.0). Future changes will apply to this new version instead of to the version that was already released. Leave blank if you don't want to bump.
   • bumpRef: Enter the Git ref you want to create the bump versions branch from, e.g. main. Leave blank if you want to use the branch selected for the workflow run. For example, if you release from a stable branch named release-prep, you may want to bump the version on main so future development work happens on the new version, then you can rebase release-prep onto main when you are ready to start preparing the next stable release.
   [Optional] Create a new pre-release and bump versions branch manually

   Manually create a new pre-release and bump versions branch

   Alternatively, you can create a new pre-release manually:

   npm run package
   # Create a new pre-release in GitHub on tag `v<version>`
   # Copy `.github/assets/release-body.md` into the release body
   # Press the "Generate release notes" button in the release creation page to generate a changelog
   # Attach contents of `release` folder to the release

   Then bump versions by running the following:

   npm run bump-versions <next_version>

   Or bump versions manually:

   git checkout -b bump-versions-<next_version>
   npm version <next_version> --git-tag-version false
   # Change version in the extension's `manifest.json`
   git commit -a -m "Bumped versions to <next_version>"; git push -u origin HEAD

3. In GitHub, adjust the new draft release's body and other metadata as desired, then publish the release.

4. Open a PR and merge the newly created bump-versions-<next_version> branch.

Bumping version without publishing a release

Sometimes, it may be useful to change the version without publishing a release.

To bump versions without publishing a release, manually dispatch the Bump Versions workflow in GitHub Actions targeting the branch on which you want to change versions. Alternatively, you can run the bump-versions npm script. This workflow will create a branch named bump-versions-<version> from the target branch (or, if running the script, your current head) with the needed changes. Open a PR and merge that new branch into the branch on which you want to change versions.

This workflow has the following inputs:

• newVersion: enter the version you want to bump to (e.g. 0.3.0-alpha.0). Future changes will apply to this new version instead of to the version.

For example, to bump branch my-branch to version 0.2.0, run the following:

git checkout my-branch
npm run bump-versions -- 0.2.0

Then create a PR and merge the bump-versions-0.2.0 branch into my-branch. my-branch is now ready for release.

Publishing problems

Following are some problems you may encounter while publishing and steps to solve them.

@swc/core Failed to load native binding

If you see the following error in the GitHub Actions workflow logs while packaging:

Module build failed (from ./node_modules/swc-loader/src/index.js):
Error: Failed to load native binding

Please see "Failed to load native binding" in the Troubleshooting guide for how to solve this problem.

To update this extension from the template

This extension project is forked from paranext-extension-template, which is updated periodically and will sometimes receive updates that help with breaking changes on paranext-core. We recommend you periodically update your extension by merging the latest template updates into your extension.

To set up this extension to be updated from the template, run the following command once after cloning this repo:

git remote add template https://github.com/paranext/paranext-extension-template

To update this extension from the template, make sure your repo has no working changes. Then run the following commands:

git fetch template
git merge template/main --allow-unrelated-histories

For more information, read the instructions on the wiki.

Note: The merge/squash commits created when updating this repo from the template are important; Git uses them to compare the files for future updates. If you edit this repo's Git history, please preserve these commits (do not squash them, for example) to avoid duplicated merge conflicts in the future.

Special features in this project

This project has special features and specific configuration to make building an extension for Platform.Bible easier. Rather than duplicating the full explanation here, please refer to the Special Features in this project section of the multi-extension template README for details on these features.