Viewport Uploader

Introduction

The viewport-uploader package is a node module to upload local resources to Scroll Viewport App inside Atlassian Confluence. For example, it can be used as part of a webpack build process to automate building and uploading a theme.

Note: viewport-uploader was formerly known as gulp-viewport. Read more about the name change in the CHANGELOG.

Getting started with Scroll Viewport theme development

See the basic example on how to use viewpoort-uploader with webpack as a starting point for Scroll Viewport theme development.

Create Environment Config

Viewport Uploader uses Confluence environments specified in ~/.vpconfig.json. Use this file to provide credentials and Confluence base url that will be used for uploading.

Create the file .vpconfig.json in your home directory and add your Confluence environments similar to the example below.

// ~/.vpconfig.json

{
  "DEV": {
    "envName": "DEV",
    "confluenceBaseUrl": "http://localhost:8090/confluence",
    "username": "admin",
    "password": "admin",
    "spaceKey": ""
  },
  "PROD": {
    "envName": "PROD",
    "confluenceBaseUrl": "https://example.com/confluence",
    "username": "admin",
    "password": "admin",
    "spaceKey": "prodspace"
  }
}

API Documentation

The ViewportTheme class provides methods for uploading resources to Scroll Viewport.

Getting started

This is a full example of how viewport uploader works. See the sections below for further details.

const ViewportTheme = require('@k15t/viewport-uploader');

// Initialize the theme instance
const themeOptions = {
    // identifies the theme in the Scroll Viewport app
    themeName: 'my-viewport-theme', 

    // identifies the environment inside the `~/.vpconfig.json`
    envName: 'DEV' 
}

const theme = new ViewportTheme(themeOptions);

// Upload theme code
const uploadOptions = {
    glob: 'build/',
    sourcePath: 'build/',
    targetPath: ''
}

theme.upload(uploadOptions, true);

Initialize a ViewportTheme instance

const ViewportTheme = require('@k15t/viewport-uploader');

const theme = new ViewportTheme({
    themeName: 'my-viewport-theme',
    envName: 'DEV'
});

Initialize a ViewportTheme instance – Using environmental variables

Alternatively environmental variables can be set. This is especially useful for CI/CD pipelines. If all of the following environmental variables are set, they will be preferred. Argument options from eg ~/.vpconfig.json will be ignored.

Methods

All methods are async methods that return a promise.

Create a theme

// Creates a theme with the `themeName` in Scroll Viewport

await theme.create();

Must be run before any other method as it initialises internal variables required by reset() and upload().

Check if a theme exist

// Checks if a theme with the `themeName` exists in Scroll Viewport

await theme.exists();

Is executed at the beginning of every method, i.e. no need to run it on it's own, every method has existence check built in.

Reset a theme

// Resets a theme with the `themeName` in Scroll Viewport, deletes all resources but doesn't delete the theme itself

await theme.reset();

Upload a theme

await theme.upload({
    glob: 'build/',
    sourcePath: 'build/',
    targetPath: ''
}, true);

⚠️   Paths should follow this pattern:

# Correct: path with a trailing slash and without a leading slash
your/custom/path/

# Incorrect:
/your/custom/path/
/your/custom/path
your/custom/path