App packages overview
App packages are only supported in TypeScript apps and where the @journeyapps/runtime-build version exceeds 2.0.0.
App packages provide a way to write and maintain reusable code throughout an application while also providing a way to run tests, generate PDFs and create custom <html/> components.
Previously, developers could only bind and maintain a single source file to an <html/> component within OXIDE (by uploading it as an asset). With app packages, developers can maintain large custom HTML projects in OXIDE very easily, thereby improving developer productivity.
Example use cases
Custom
<html/>componentsOffline PDF generation (see below)
Libraries with unit tests (see below)
Overview
The high level architecture of app packages is outlined below.
A package is created from a template and source files can now be edited.
A developer triggers a deploy which sends all the source code over to the JourneyApps build system.
The JourneyApps build system starts building the app, and looks for app packages.
For each app package, the JourneyApps build system will execute the
buildcommand inside each correspondingpackage.json>scriptsection.distdirectories and other build artifacts are created, but are hidden to the developer.The build artifacts are packaged along with the compiled application and uploaded to the update system.
The JourneyApps Runtime downloads the application update along with the compiled package's build artifacts, and they are executed inside your code.
Some components such as
<html/>component can display build artifacts from an app package such as anindex.htmlfile.
Structure of a package
packages are defined inside the
/packagesdirectory in your application's project files.A package will always contain a single
package.jsonfile with:A
scriptssection that contains abuildcommand.A name that starts with
@localsuch@local/my_package.
Where can I use packages?
The initial release of packages will only be useable from within your app (i.e. the JourneyApps Runtime), but in the near future, packages will also be useable inside CloudCode tasks. This will enable you to write code that can be shared across the app as well as in CloudCode.
Types of package templates
OXIDE includes a number of package templates. These are listen when creating a new package:
Basic TS Package
This template is useful for authoring libraries or writing code which can be run in unit tests. To give this a try, follow this guide.
PDF Report
Use this package to easily create PDF reports that can be dynamically generated from within the app and rendered offline inside an <html> component. To learn more about this template, and to see an example on how to use it, follow this guide.
JS HTML Component
Use this package to create a custom HTML component , with logic written in JavaScript. It includes a webpack configuration to build the component. It includes sample code that initializes the journey-iframe-client, to allow communication between the HTML component and the app.
TS HTML Component
This template mimics the JS HTML Component template, but uses TypeScript instead of JavaScript.
React + TS HTML Component
Use this template to create a custom HTML component written in React and TypeScript. It includes sample code that initializes the journey-iframe-client, to allow communication between the HTML component and the app.
FAQs
When are app packages built?
Upon deploying your app.
How do packages differ from TypeScript app's modules?
App modules are lightweight ways to share code between views in your app. App packages can also be used to share code, however they also provide a way to run custom build commands upon a “deploy” action, and can also generate assets that can then be used in your app.
How do files within packages differ from app assets?
Static assets which are uploaded directly to the app, are simply copied in when the app is deployed, and accessible when the app runs.
Assets that are copied into packages are not directly accessible unless they go through a compilation step. Some packages such as the ones which use the PDF template as a base, contain a webpack file which compile the assets and make them accessible to the rest of the app.
Last updated
