koji-tools

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

Usage - Frontend

1. npm install --save koji-tools of course!
2. 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"
}

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

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

4. 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

1. Just like in frontend, install koji tools: npm install --save koji-tools
2. 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": "..."
}

3. 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().

• Koji.resolveSecret(key) Resolve the value of a user's secret from the Koji Keystore. Secrets are used for values that are not intended to be read by other users when a project is remixed.

Get Started at GoKoji.com

Changelog

0.5.2

• Resolve secrets

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