os-webview

What os-webview is

OpenStax os-webview is the web front end for OpenStax, the open educational resources publisher behind openstax.org. The repository builds a reader site that presents textbook and course content in the browser. The README links the OpenStax logo and the project is presented as part of the OpenStax tooling rather than a standalone product. Development depends on nvm, the Node version manager, which the README lists as the single requirement for getting started.

The application is configured through an environment variable named API_ORIGIN. That variable tells os-webview which CMS instance to use, because the settings are loaded from the CMS instance's webview-settings API rather than from a local file. The README states the default API_ORIGIN for the development script is https://dev.openstax.org. The CMS itself is a separate project, openstax-cms, referenced in the README. This design means the webview stays a thin presentation layer while the content and its configuration live in the CMS, and changing the target environment is a matter of pointing the variable at a different instance. The README does not describe the rendering internals in detail, keeping the focus on setup, build, and release steps that a contributor would run. The project is therefore best understood as a build and delivery layer for OpenStax content rather than as the content store itself.

The development workflow

The development loop is built around a few scripts in the repository. After installing nvm, a contributor clones the repository and runs script/setup to prepare the working tree. Starting the development server is done with two commands: sourcing the bootstrap script and then running script/dev. The README says this builds the site for development and opens it in the default browser using BrowserSync. The dev command creates a new dev directory from which the site is served.

Changes are meant to be made in the src directory. Webpack watches src for changes, performs the compilation and transpilation that the project needs, and updates the result in the dev directory, so the browser refreshes as files change. That watch based flow is the core of local editing. Building for production is a separate step: running ./script/build production creates a dist directory that a web server then hosts. The README notes no special server configuration is required, but serving the site over HTTP/2 is strongly recommended. The split between the dev directory and the dist directory keeps the development build separate from the artifact that gets deployed, and contributors are told which folder to edit and which to serve. The README is explicit that edits belong in src and that the build tools populate dev and dist from there, which avoids the common mistake of editing generated output.

Testing and the release process

Quality checks and releases follow a fixed routine. Running script/build and script/test locally executes the linters and the unit tests. The README also allows running the linters on their own with yarn lint and running a single test by name with yarn jest, giving a concrete example of layout.test. Coverage is reported as an HTML page that the contributor loads from /coverage/index.html at the root of the repository. The unit tests depend on the dev build existing in the dev directory, which the README calls out as a note.

Releasing is a manual, version tagged process. A contributor checks out a release branch, then updates the version field in package.json. The README says this is the only file that needs editing for versioning, and that the middle number is normally incremented while the rightmost number increments for hotfixes. Dependencies are refreshed with yarn upgrade, which updates yarn.lock, and the build and test scripts are run to confirm nothing broke. After committing, the contributor creates a tag in the form v{major}.{minor}.{patch} and pushes it, then drafts a GitHub release whose title matches the tag. The README instructs keeping the release as a pre release until it has been deployed to production, so the published version reflects what is actually live.

Editorial conclusion

os-webview is written in TypeScript and hosted at github.com/openstax/os-webview.