@dx-samples/one-page-wonder-types

one-page-wonder-types

Container project to bundle WCH data records as an npm module. Such a module can then be used as a dependency by single page application projects to populate a tenant with data.

Setup

• Create a new repository on github.
• Invoke git remote add upstream [e-mail]:DX-Samples/one-page-wonder-types.git on the command line.
• Invoke git pull upstream master to get the initial content.
• Invoke git push to push the initial content to your repository.
• Modify name and description in the package.json file (and probably author and repository URL).

Get Ready

In order to add content to your project you will need to use wchtools to pull data in the correct format from your tenant. Apply the following steps to prepare your environment.

• Follow the steps outlined in Credential Management to store your credentials.
• Modify username and API URL in the file data/.wchtoolsoptions.json.

Add Data

In general you only want to ship a subset of all data deployed to your WCH Tenant in your library. These data records have to be placed in the data folder. We suggest the following process to identify the correct data set:

• First pull all data into a temporary folder.
• Then use a merge tool to selectively only copy the relevant files into the data folder. We like BeyondCompare for this step, but you are free to use any tool.

Pull data into a temp folder

Use the following command:

npm run gen:pull

This will copy all data into a tmp folder. This folder will be excluded from your repository automatically, you do not need to care about its size. It's also OK to delete the folder.

Identify the correct subset

It makes sense to distinguish between two types of data, very similar to interfaces and implementation in a coding environment.

Interfaces: this subset contains all content types, image profiles, etc that describe your data model in WCH. This also includes all assets referenced by these artifacts, such as thumbnail images or referenced categories. There is no automated way to identify the complete set, you will have to select the desired types and then manually follow all dependencies.

Implementation: this subset contains the content items, assets, renditions, etc based on the interface types.

Both aspects of your data should be shipped as separate modules, because they might be used as prerequisites by other projects. Consider for example a UI library that contains UI components that can be reused on your single page application. This UI library would prereq the interface module, since it builds on top of the content types. But it has no dependency on the actual data content. In fact there even might be different implementation data sets all building on top of a common interface module.

Specify dependencies

If you are packaging an implementation like library, you will have to specify the interface library (and potentially others) as dependencies:

• Add the module identifier of your dependency to your package.json file in the dependencies section.
• Add the module name to the list of wchtools-dependencies.

package.json:

"dependencies": {
  "my-interface-module": "*"
},
"wchtools-dependencies": [
  "./data", "my-interface-module"
]

Test your package

Since the process to select your data subset is basically manual, it is pretty error prone. You want to test your package before shipping it. For this purpose we recommend to always work against an empty tenant.

Delete all content. Use with care, this really deletes all content on the tenant. Only execute this if you have made a backup.

npm run deploy:delete

Deploy your library:

npm run deploy:push

The deploy:push command should run without errors.

Build and Deploy your package

We need to prepare our package in the correct format and then publish it to npm.

Run the following to prepare your package in a suitable format:

npm run build

This creates the desired artifacts in the dist folder.

Run the following to publish your package to the registry.

npm publish dist

Automated Build

We recommend to build and deploy your package automatically, e.g. by using Travis CI. Edit the .travis.yml file and add your email address.

In the Travis CI add a secure environment variable NPM_TOKEN and enter your npm token.

Your project will then be deployed automatically whenever you execute a tagged git commit.

Git Lifecycle

Execute your git check-ins as usual. Whenever you push, this will trigger a new Travis CI build. When you are ready to release a new version, call:

npm version minor
git push --follow-tags

For reference see the documentation on npm version and git push.