one-page-wonder-content
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 git@github.ibm.com:DX-Samples/one-page-wonder-content.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.