faithlife-html-component-tools

HTML Component Tools

Project Generators

Component Projects

Use this generator for starting a new project for a reusable React-based UI component.

# Create and enter your project directory 
mkdir my-component; cd !$
 
# Initialize the git repo 
git init
 
# Install yarn, if necessary 
See installation instructions at [yarnpkg.com](https://yarnpkg.com/en/docs/install)
 
# Install the tools 
npm install -g faithlife-html-component-tools
 
# Run the generator 
init-html-component

Answer prompts from the generator. It will create the default directory structure and configuration files needed to begin development.

What next?

• Review the Cross-platform HTML Component Development Guidelines.
• Flesh out or replace the component in src/index.jsx.
• Test your components by keeping src/__tests__ up to date. Add more __tests__ directories adjacent to new components or utilities.
• Use examples/basic to test your component. Add more example apps as needed. These can serve as harnesses for manually testing your component, as well as documentation for other users of your component.
• When you're ready, yarn publish your component. Make sure the name and version in package.json accurately describe the module being published.
• Upload your source maps to Raygun if needed, using the archive-source-maps and publish-source-maps commands. Here's How.

The following run scripts are available:

• yarn start -- start a development server hosting the example apps.
• yarn lint -- run ESLint.
• yarn test -- run all tests located in __tests__ directories.
• yarn tdd -- run tests in watch mode, re-running when source files change.
• yarn build -- clean, lint, test, and build your component. Output suitable for publishing is written to dist/.

Component Consumers

Use this generator for creating a simple interop application to wrap a component for use in Logos desktop embedded views.

This should be run in the DigitalLibrary project under the directory where your panel or feature lives. E.g., DigitalLibrary/src/LDLS4/Panels/AwesomeDesktopPanel/Html

# Create and enter your project directory 
mkdir Html; cd !$
 
# Install the tools 
npm install -g faithlife-html-component-tools
 
# Run the generator 
init-html-consumer

Answer prompts from the generator. It will create the default directory structure and configuration files needed to begin development.

What's next?

• You should now be able to navigate your WebBrowserModel to the dist/index.html file and see some rendered output.
• Flesh out the application in src/. You'll probably want to use npm install to pull in some other Faithlife components.
• Mark all files in dist/ that are necessary to run as embedded resources in Visual Studio.
• npm run build will produce a debug build in dist/.
• When you're ready, run npm run build:release. Commit the contents of dist/ to git.

Source Maps

The embedded-resource-tools module contains two commands to facilitate publishing source maps to Raygun. Generally, this is a two step process.

• Archive: You might not need to publish every map file, just the ones that ship to users. Use the archive command to store any and all maps somewhere until the maps need to be published.
• Publish: Performs the actual upload to Raygun.

For example, in a component consumer's Jenkins build, you can add a version of the following to perform an archive and an upload. The archive is enabled from publish-nuget-package-if-necessary via the presence of SOURCE_MAP_ARCHIVE_DIR, and the upload is enabled by RAYGUN_UPLOAD_URL. This example uploads all maps to a Raygun application for alpha builds.

set -e;

export SOURCE_MAP_ARCHIVE_DIR="\\\\desk-dev-fs02\\packages\\LogosDesktop\\ComponentHostSourceMaps";
export RAYGUN_UPLOAD_URL="https://app.raygun.io/jssymbols/1il7xg";
export RAYGUN_API_TOKEN="A TOKEN";

for d in */ ; do
    pushd $d &&
    yarn && yarn build:release && yarn publish-nuget-package-if-necessary
    popd;
done

To perform a publish from an archive, you can run the publish-source-maps command directly with the same environment variables appropriately set. See this gist for an example.