koji-tools

A simple library for adding koji-specific features to a node project.

Usage - Frontend

npm install --save koji-tools of course!
Add a watcher to your development setup In your package.json file, add a prestart script to your scripts section. You may also optionally add PWA support with koji-tools through a postbuild script shown below:

"scripts": {
    "prestart": "koji-tools watch &",
    "start": "...",
    "build": "...",
    "postbuild": "koji-tools pwa"
}

Add a Koji.pageLoad(), function to your app's main js file. App.js

import Koji from 'koji-tools';
...
Koji.pageLoad();
...

Use koji-tools in your application to get Koji Customization options and other features:

import Koji from 'koji-tools';
// If I had a 'backgroundColor' property in a 'colors' customization file. 
console.log(Koji.config.colors.backgroundColor);
// If I had a route TestRoute
Koji.request(Koji.routes.TestRoute).then((response) => {
    console.log(response);
})

Auto test VCC's

vccTest is a function to auto test koji VCC's by automatically changing all VCC's, or printing un-handled VCC's to the console.

To run vccTest Open the browser console and run:

vccTest();

Usage - Backend

Just like in frontend, install koji tools: npm install --save koji-tools
Add a watcher to your development setup In your package.json file, add a prestart script to your scripts section.

"scripts": {
    "prestart": "koji-tools watch &",
    "start": "..."
}

Import koji-tools in your routes to get access to Koji.config. Example:

import Koji from 'koji-tools';

export default async (req, res) => {
    console.log('request running...');
    const content = Koji.config.strings.content;
    res.status(200).json({ content });
}

*NOTE: As of 0.4.3, only Koji.config is supported for backend node.js usage. Other koji-tools functionality is not available.

API

Koji.watch() Server Side function that sets file watchers on all .koji customization files and allows for hot reloading of these properties.
Koji.pageLoad() Sets up Koji.config parameters for each client and handles communication between the Koji live preview iframe and your app.
Koji.request() Wrapper for fetch that takes objects from Koji.routes.
*Note: as of 0.4.2, a cache option can be added to a routes koji.json file, default is no-cache in order to avoid stale caching.
Koji.pwaPrompt() After the 'pwaPromptReady' event has fired, this function will make a popup installation prompt appear.
*Note: this function must be run from some user input. (like onClick)
Koji.config An autogenerated list of all of the Koji Customization Controls (CVV's) your application has setup. when Koji.watch() is being used this list updates automatically.
Koji.routes A autogenerated list of routes based on koji.json files in your project that are used in Koji.request() to request the backend of you app.
Koji.on(event, callback) Register a callback on a koji event. events - change

Koji.on('change', (scope, key, value) => { ... });

Where scope is the file that has been changed and key and value are the json item with its new value.

Koji.on('pwaPromptReady', () => { ... });

On a deployed project that has koji-tools pwa in the "postbuild" section of the package.json file, this event will fire when the PWA Install Prompt is ready to be called. See Koji.pwaPrompt().

Get Started at GoKoji.com

Changelog

0.5.1:

Starting to move away from strict dependance on metadata.json, allow for plugin PWA manifest support.

0.5.0:

VCC testing tools added

0.4.3:

Support for backend to use Koji.config

0.4.2:

added caching options to Koji.request that are customizable in a routes koji.json
changed default caching stategy to no-cache to keep request freshness

0.4.1:

minor bug fixes

0.4.0:

Added pwa prompt support
the function Koji.pwaPrompt()
the callback handler Koji.on('pwaPromptReady', () => { ... })

0.3.0:

Added easy to setup pwa support for projects with koji tools

0.2.0:

Added callback handlers
minor usability fixes

0.1.0:

Initial commit.
Barely working but technically working

treeniap/koji-tools