Skip to content

Latest commit

 

History

History
197 lines (136 loc) · 8.5 KB

README.md

File metadata and controls

197 lines (136 loc) · 8.5 KB
Raw

Scripture Editors

This monorepo contains packages for various Scripture editors.

Each Scripture application's editor will have many behaviors in common with other Scripture applications. Each will need some features that are unique. We are developing all of these parts in a compatible way and in one place in order to maximize collaboration and sharing.

In this monorepo:

  • Each application produces their own editor package - the application uses the package produced from this repo because the source is there.
  • Common nodes, plugins, and formatters for the toolbar plugin.
  • Specific sets of nodes, plugins, and formatters for each data type extending from the common items where applicable.

Sharing in this monorepo is a commitment to maintain and organize it. Each application package is free to move in its own direction but keeping in mind items that can be pushed up outside the specific editor package to be used in common.

Developer Quick Start

  1. Install Volta.
  2. Clone the monorepo: 
    git clone https://github.com/BiblioNexus-Foundation/scripture-editors.git
cd scripture-editors
pnpm install
  3. Install Nx globally (note we intentionally use npm rather than pnpm for global installs, see JavaScript Tool Manager): 
    npm i -g nx
  4. Run one of the top level developer environments (see the Nx Graph below), e.g.: 
    nx dev perf-react

JavaScript Tool Manager

You can use Volta with this repo to use the right version of tools such as Node.js and PNPM.

If you don't use Volta just look at the volta property in package.json to see the right tool versions to install in your preferred way.

NOTE: there is a known limitation using PNPM with Volta. So to install packages globally, use NPM instead of PNPM (only for global installs). For an example, see step 2 of Developer Quick Start.

Nx Monorepo Build System

Source Package
perf-vanilla
perf-react
platform Github Tag
scribe Github Tag
shared-react
shared
utilities Github Tag 
---
title: Nx Graph
---
graph TB
  V(perf-vanilla) --> S(shared)
  R(perf-react) --> S
  P(platform) --> SR
  SB(scribe) --> SR
  SR(shared-react) --> S
  R --> SR
  P --> S
  SB --> S
  S --> U(utilities)
  P --> U
  SB --> U
Loading

✨ This workspace has been generated by Nx, a Smart, fast and extensible build system. ✨

Nx Installed Globally?

If you haven't installed Nx globally (as recommended in step 2 of Developer Quick Start), then just prefix each call to nx with pnpm, e.g. pnpm nx build perf-react.

Running tasks

To execute tasks with Nx use the following syntax:

nx <target> <project> <...options>
# e.g.
nx build perf-react

You can also run multiple targets:

nx run-many -t <target1> <target2>

..or add -p to filter specific projects

nx run-many -t <target1> <target2> -p <proj1> <proj2>

Targets can be defined in the package.json or projects.json. Learn more in the docs.

Generate code

If you happen to use Nx plugins, you can leverage code generators that might come with it.

Run nx list to get a list of available plugins and whether they have generators. Then run nx list <plugin-name> to see what generators are available.

Learn more about Nx generators on the docs.

Want better Editor Integration?

Have a look at the Nx Console extensions. It provides autocomplete support, a UI for exploring and running tasks & generators, and more! Available for VSCode, IntelliJ and comes with a LSP for Vim users.

Ready to deploy?

Just run nx build perf-react to build that application. The build artifacts will be stored in the dist/ directory, ready to be deployed.

Set up CI!

Nx comes with local caching already built-in (check your nx.json). On CI you might want to go a step further.

Connect with us!

Testing

The unit tests run automatically on each GitHub PR (see test.yml).

To run all TS unit tests:

nx run-many -t test

To run all TS unit tests for a single package (in this example the shared package):

nx test shared

To run all TS unit tests watching for file changes:

  • On Windows: 
    nx watch --all -- nx test %NX_PROJECT_NAME%
  • On Linux or macOS: 
    nx watch --all -- nx test \$NX_PROJECT_NAME

You can also use the recommended VS Code extensions to run tests there. This is particularly useful for running individual tests and debugging.

Formatting, Linting and Typechecking

Formatting happens automatically when you commit. If you use VS Code with this repo's recommended extensions, files will be formatted when you save.

To check TypeScript for readability, maintainability, and functionality errors, and to check a few other files for proper formatting, run the following from the repo root (or just use VS Code with this repo's recommended extensions).

nx format:check # to check formatting
nx format:write # to fix formatting
nx run-many -t lint # to check linting
nx run-many -t typecheck # to check types

Collaborative Web Development Environment

Thanks to CodeSandbox for the instant dev environment: https://codesandbox.io/p/github/BiblioNexus-Foundation/scripture-editors/main

Plain Vanilla JS and React

Lexical works with plain-vanilla JS/TS as well as with React. To that end, the editor packages in this repo perf-react and perf-vanilla are 2 editor components that behave the same to edit the PERF data format.

If you are using a framework other than React and need to wrap a plain-vanilla JS editor for your framework, you could add your own vanilla TS editor package to this repo. By comparing perf-vanilla and perf-react you can see how to take any existing React plugins you might want and convert them to vanilla TS.

License

MIT © BiblioNexus Foundation