Nonagons Please Me

    @dx-samples/one-page-wonder-types
    TypeScript icon, indicating that this package has built-in type declarations

    6.0.4 • Public • Published

    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 git@github.ibm.com: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.

    Install

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

    DownloadsWeekly Downloads

    1

    Version

    6.0.4

    License

    MIT

    Unpacked Size

    39.2 kB

    Total Files

    23

    Last publish

    Collaborators

    • mburati
    • carstenleue
    • sterbling