README.md

lexicon

The Platform.Bible extension for managing the lexicon for your project's target/vernacular language.

Summary

The general file structure 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/components/ contains stand-alone (i.e., WebView- and service-independent) components
  • src/main.ts is the main entry file for the extension
  • src/services/ contains services to be used with networkObjects.set() in src/main.ts
  • src/types/lexicon.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
  • src/utils/ contains utility classes and functions
  • src/web-views/ contains WebView components to be used with registerWebViewProvider() in src/main.ts
    • *.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
• webpack/ contains configs, scripts, and utils used by webpack.config.ts in the root folder
• 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

Configure paths to paranext-core repo

In order to interact with paranext-core, you must 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. For example, if you cloned this repository in C:\dev\LexBox\, you would clone paranext-core in C:\dev\paranext-core\.

Install dependencies:

1. In the paranext-core repository, run npm install
2. In this folder, run npm install to install local and published dependencies

To run

First, you must build FieldWorks Lite (FW Lite) using the task defined in this folder:

task build-fw-lite

This is a normal production build, so changes to FW Lite files will not be rebuilt automatically. If you want to do FW Lite development, look at README.md

Running Platform.Bible with this extension

Warning: you must not use pnpm, only npm.

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

Using this extension with another development extension

This extension has a network service that can be used by other extensions. Here's how to make it available for active development of another extension:

1. In platform.bible-extension/: run task build-fw-lite, then npm run package, then npm run core:copy-package.

2. In .eslintrc.js, in the 'import/no-unresolved' rule, add 'lexicon' to the ignore array:

-'import/no-unresolved': ['error', { ignore: ['@papi'] }],
+'import/no-unresolved': ['error', { ignore: ['@papi', 'lexicon'] }],

3. Example uses of this network service are found in add-word.web-view.tsx and find-word.web-view.tsx. Note the following key elements:

• With types NetworkObject imported from '@papi/core' and IEntryService imported from 'lexicon':

const [lexiconService, setLexiconService] = useState<NetworkObject<IEntryService> | undefined>();

• With networkObjects imported from '@papi/frontend', get the network service via

useEffect(() => {
  networkObjects.get<IEntryService>('lexicon.entryService').then(setLexiconService);
}, []);

• The current PT project id (which the example WebViews get via their props).
• Call any method defined in entry-service.ts
  • To use lexiconService.addEntry, also import types IEntry and PartialEntry from 'lexicon'.
  • To use lexiconService.getEntries, also import types IEntryQuery and PartialEntry from 'lexicon'.

Sync template updates into this extension

This extension is based on paranext-extension-template. Tooling updates (linting, formatting, build config, etc.) can be pulled in interactively using the sync script.

Prerequisites

Clone paranext-extension-template as a sibling of the languageforge-lexbox monorepo root:

git clone https://github.com/paranext/paranext-extension-template ../paranext-extension-template

Running the sync

npm run template:sync

The script:

1. Runs git pull --ff-only in the template repo to get the latest changes.
2. Lists every tracked template file (respecting .gitignore) and shows a git diff for each file that differs from this extension.
3. Prompts you to choose an action for each differing file.

Prompt options

For each differing file the prompt shows (color-coded to match the diff):

Key	Color	Action
e	green	Keep the extension version — no change
t	red	Apply the template version directly
d	yellow	Defer — skip for now and revisit after the main pass
b	orange	Do both — copy the template version, then defer to review/edit

Files that have extension-specific modifications (package.json, manifest.json, README.md, config files, etc.) have [t] blocked, ensuring that if you apply the template version, you have to review them.

Files in contributions/ and assets/ are surfaced for reference but block both [t] and [b] — adapt those manually.

Deferred files

After the main pass, deferred files are listed and the script pauses so you can edit them. Press Enter to do another pass over only the deferred files. Repeat until all deferred files are resolved.

Final steps

• Commit changes to your working branch.
• Review a diff of that branch from develop to verify you haven't removed extension-specific updates.
• Delete package-lock.json and node_modules/, then run npm i --no-scripts to regenerate package-lock.json.
• Run npm run build and npm run lint and fix any failures. If failures arise from (e.g.) changed lint rules in the template, don't just revert the rule change; either update the code or add a targeted exemption.
• Commit all, push, and create a pr.