magnitce-code-example

Overview

A custom HTML element that renders code in a syntax-highlight text block, and the results of that code in a display frame.

||||| |-|-|-|-| |Package size, verbose:|~78kb|Package size, minified:|~42kb|

Quick Start

Links

Demo:

https://magnitce-code-example-e81613.gitlab.io/

Documentation:

https://magnitce-code-example-e81613.gitlab.io/documentation

Automated Testing:

https://magnitce-code-example-e81613.gitlab.io/test-runner

Repo Notes

This section provides instructions for how to use the repo to develop the library.

Installation

Install the repo using a package manager:

npm install

Configuration

tsconfig.json

The tsconfig.json file is generated by the vite dependency and has not been modified by this library. It uses strict linting and defaults to es modules, rather than commonjs modules. For more information about each of the tsconfig.json options, see the tsconfig documentation.

vite.config

The vite.config file sets defaults options for the dev, build, and release processes, which allows the code to be packaged as a library (rather than a website) and defines custom inputs and outputs to exclude tests and create both es and umd modules. It also includes settings that allow for multiple file outputs with well-defined names and selective minification. For more information about configuring vite, see the vite config documentation.

vite.config.tests.ts

This specialized vite.config file defines custom inputs and outputs that include tests and then are packaged into the test-runner directory, rather than built to the dist directory.

Scripts

dev

Use vite to begin a server with Hot Module Replacement, which will automatically reload any time a change in a source file is saved.

build

Use vite to transpile the source code into code chunks or library files. Files are output into the dist directory by default.

preview

Use vite to serve the dist directory. Useful for non-library projects, where the dist directory will contain an index.html file, or other browse-able entry point.

test:build

Use vite to transpile all files with a .tests.[ts|js|tsx|jsx] extension into the test-runner subdirectory. Creates javascript files that can be served to the <test-runner> and <code-tests> components.

test

Runs the test:build script and then serves the library website using serve, to prevent module resolution issues that occur when running the dev script.

changeset

Runs the npx @changesets/cli command to create a new changeset which will prepare the library to be published.

release

Use vite to transpile the source code and then use changesets to begin the publication procedure for the repo environment (github or gitlab).
If this script is run during CI/CD for the main branch, the library is published to npm. If it is run during CI/CD for any other branch, the library is linted and compiled. It is expected that this command will only be used by a CI/CD pipeline, and never by a library dev. Running the release script on a local codebase is not supported.

lib

Creates a build that can be used as a dependency for the introduction theme, and then copies that dependency into the introduction theme's libraries directory. This script is unique to this library because it is being used by the website that is presenting it.

Publishing

Releasing with changesets

Publishing is handled using the changesets library which starts the process by requiring a manual entry into a running version log. Once you have defined a set of changes as a version change, the automated processes can prepare the library to be published on to npm. When the automation has prepared the release, it will create a pull request from a new branch containing the release package. The publishing developer will be required to merge that branch into main, using the pull request, in order to publish a new version.

The step-by-step process is outline below for both Github and Gitlab:

Github Steps

1. Run changeset command: npm run changeset | bun run changeset | pnpm changesets | yarn changesets | npx @changesets/cli
2. Log version info: Add a message that describes the changes in this version
3. Check in: Push changes to repo
4. Merge: Merge branch into main
5. Merge Automation Branch: Await repo automation's creation of a new pull request from a newly created branch. Accept the pull request, merging the branch into main.

After automation completes, the new version will be published to NPM.

Gitlab Steps

1. Run changeset command: npm run changeset | bun run changeset | pnpm changesets | yarn changesets | npx @changesets/cli
2. Log version info: Add a message that describes the changes in this version
3. Check in: Push changes to repo
4. Merge: Merge branch into main
5. Merge Automation Branch: Await repo automation's creation of a new merge request from a newly created branch. Merge the merge request into main.

After automation completes, the new version will be published to NPM.

Dependencies

Library Dependencies

prism-esm

The prism library provides code highlighting for arbitrary snippets, supporting a wide variety of languages. This dependency is a wrapper around the prism library which allows it to be used more easily in es modules. Including this library provides syntax highlighting for javascript, html, and css, as well as a plugin engine that supports other language syntaxes.

Development Dependencies

typescript

Typescript provides type checking at dev time which adds compile-time safety to the codebase for a wide range of issues. For more information on Typescript, visit its website.

@changesets/cli

The changesets library uses a strict process to handle versioning and publishing which makes the update and deployment of any library to NPM a structured and repeatable series of steps. Versioning is managed by a command-line utility which enforces release notes and semantic versions. Publishing is handled automatically by CI/CD pipelines when code is checked in. The structure allows for automated pipelines to handle linting and testing, while requiring manual directives to invoke action. Versions are not accidentally published, because all code changes that haven't been packaged into a changeset are transparent to the library. As soon as a version is updated (by the library), the CI/CD pipelines will trigger and the library developer will need to merge branches in order to complete the publishing. By enforcing these procedures, changesets keeps this library releasing traceable and well-versioned packages.

vite

Vite is a packaging library that includes a lot of features that make development faster and easier. Packaging and minifying are built in as well as "hot module reload" so that saving any source file will reload the script in the development environment instantly. That is made even better because Vite also dynamically swaps typescript references for javascript references, meaning that a development build can target and debug with the typescript files directly. It is also configurable enough to account for a wide variety of project types.

vite-plugin-dts

This plugin for the vite library allows the packaging process to also produce a .d.ts file to describe all of the Typescript types exposed by the library. Without that export, other projects that use Typescript would not be able to see the full manifest of exported types.

@rollup/plugin-terser

This plugin, which was developed for one of vite's dependencies (rollup) but is used in this project by vite, provides a type of minification that is not supported by the default library. Using this plugin, the library can be packaged with both unminified and minified code, so that developers who implement the library can debug the code in un-minified files, while still being able to ship a minified version without having to minify it in their own projects.

@magnit-ce/test-runner

This library adds custom HTML elements that allow developers to run simple definitions for automated tests directly in a browser. These elements are used in the test-runner directory to provide live automated testing.

glob

glob is a low-level library that provides full-featured search capabilities to a command-line input. These search features are used by this library to differentiate between test files and source files within the vite.config files.

@web/dev-server

This library provides a local server to serve the project directory without module resolution conflicts between vite and the <test-runner> element. This library is not necessary if vite can be configured to stop wrapping import links for specific run modes (like "testing" vs "development"). At this point, no such configuration has been included in this project so the web/dev-server library is used as a work-around for that deficiency.

Warning - Non-production package

This project is being prepared for production, but is not ready to be used as a dependency for anything. There will be breaking changes and unrecoverable states. Do not use until this warning has been removed.

When the library reaches the 1.0.0 designation, that will be a production package. From that point, you can use the major version number (1 in 1.0.0) to recognize when breaking changes are introduced.