1.0.2 • Public • Published

    WABS Starter

    This starter is preconfigured to optimize development and simplify deployment. It will work with very little additional effort on your part. This readme serves as a guide to using the starter.

    Estimated Set Up Time: 2 minutes

    Table of Contents

    Quick Start

    This section details instructions for getting started with the development of your application.

    1. Clone the project from github: git clone git@github.com:byu-oit/wabs-starter.git.

    2. Log in to AWS

      1. Install AWS Login: https://github.com/byu-oit/awslogin

      2. Run the command: awslogin to log in

      3. Select the account: dev-oit-byu

    3. From within the project directory run the command: npm run dev

      By default this will also cause the NodeJS server to run in debug mode on port 9229, allowing you to set up a remote debug session.

    4. Open a browser to http://localhost:8460

    Eventually you will need to set up your own WSO2 application and have your app use that instead of the demo-app. See the documentation at https://www.npmjs.com/package/byu-wabs to get started with that.

    What's Included?

    • Authentication with CAS.

    • Authorization with WSO2 (for wabs-demo application - Set up own WSO2 application).

    • Using the latest BYU theme.

    • Interoperability with the C-Framework.

    • Vue Router

    • Vuex (Vuex Video Tutorial)

    • Gulp, Webpack, and BrowserSync

    • SCSS Transpiler

    BYU Plugin

    The BYU plugin for vue adds various bits of functionality for controlling site title, navigation menu, authenticated state, and search. You can access the functionality of these components within a Vue component using this.$byu or outside of a component using app.$byu.

    Site Title

    The site title is stored in a Vuex store.

    Set Title within a Component

    this.$store.commit('siteTitle', 'My New Title')
    this.$byu.site.title = 'My New Title';   // will commit to the store for you

    Get Title within a Component

    let title;
    title = this.$store.byu.title;
    title = this.$byu.site.title;       // will get the title from the store

    Update Title Per Route

    You can update the title for a route change within the route component's configuration. The byuTitle function will be called when the route changes and uses this component. The selected parameter is the navigational link object that was selected to navigate to this page.

        export default {
            byuTitle(selected) {
                return 'Demo Site | Home';

    Site Navigation Menu

    The navigational menu that is part of the BYU header is stored in the Vuex store as an array of objects. Each object should have the following structure:

        href: '/',  // the path to navigate to
        title: 'Link title',
        callback: link => { ... }   // optional function to perform custom navigation

    Set Navigation within a Component

    You can update the navigational menu within a component. This must be an array of objects. If the array is empty then the navigation menu will automatically be hidden.

    this.$store.commit('siteNavigation', [
        { href: '/', title: 'Home' },
        { href: '/page1', title: 'Page 1'
    // will commit to the store for you
    this.$byu.site.navigation = [
        { href: '/', title: 'Home' },
        { href: '/page1', title: 'Page 1' }

    Get Navigation within a Component

    let nav;
    nav = this.$store.byu.navigation;
    title = this.$byu.site.navigation;          // will get the title from the store

    Update Navigation Per Route

    You can update the navigation for a route change within the route component's configuration. The byuTitle function will be called when the route changes and uses this component. The selected parameter is the navigational link object that was selected to navigate to this page. The links parameter is the array of links that existed prior to reaching this page.

        export default {
            byuNavigation(selected, links) {
                return [
                    { href: selected.href, title: selected.title },
                    { href: '/page1', title: 'Page 1' }

    Site Search

    The search box can be enable or disabled from within the src/js/app.js file where the BYU plugin is included. Remove the search property to disable search entirely.

    Vue.use(BYU, {
        search: {                       // remove search object to disable search
            autoSearch: false,          // set to true to run search after autoSearchDelay
            autoSearchDelay: 300,       // the number of milliseconds to wait before auto searching
            callback: function(value, submitted) {  // the function to execute when search occurs.
                console.log('Searched for ' + value)
            value: ''                   // value to initialize search box with

    The callback function received two parameters:

    1. The search term.

    2. A boolean that is true if the value was submitted for search or false if the search was caused by auto search.

    Get or Set Search Value

    Within a Vue component you can get or set the search value.

    this.$byu.search.value = 'New Search Value';    // set value
    const value = this.$byu.search.value;           // get value

    Perform a Manual Search

    You can trigger the search manually by calling the search function. This function takes two optional paramters.

    1. The search term. Defaults to what is in the search box.

    2. Whether it is being submitted instead of by auto-search. Defaults to true.

    this.$byu.search('New search term');

    File System Structure

    - server (NodeJS express server code)
    - src (the front-end code)
        - components (a directory for your Vue components)
        - css (contains your main CSS file: main.scss)
        - js (contains your main JS file: app.js)
        - plugins (contains custom Vue plugins)
        - router (contains the router and Vue components used as views)
        - store (contains the Vuex store, including some modules)
    - tasks (the code that builds your app)
    - www (your built code)
    - config.js (the build, run, and development configuration)


    There are two types of configuration:

    1. The WABS middleware configuration. To get this set up you'll want to modify the code in server/index.js and follow the instructions at https://www.npmjs.com/package/byu-wabs. This is where you'll be able to name your application and link it to your own WSO2 application instance.

    2. The build / run configuration. This can be found in the project root directory at config.js. The configuration is documented.

    Production Build

    Running your server with npm run dev will not store the build.js file on the hard drive. To accomplish that you'll want to run the command npm run build. You're deployment process should run this command with the environment variable NODE_ENV or HANDEL_ENVIRONMENT_NAME set to 'production'.


    • Error: Unable to load WABS configuration

      The WABS middleware was missing part of the required configuration. Possible solutions:

      1. Make sure that your still logged in to AWS using the AWS login script. In the terminal execute the command awslogin. Once logged in then try to start the server again.

      2. Make sure that you have a configuration defined in the AWS parameter store for your application.

      3. If you are using a local file for the configuration (not recommended) then verify that the file exists at the location you've specified.

    • Error: Unable to start server

      This error is pretty generic. Try looking a little higher in the counsole output for more specific errors.




    npm i @byu-oit/wabs-starter

    DownloadsWeekly Downloads






    Unpacked Size

    53.7 kB

    Total Files


    Last publish


    • yoshutch
    • lehinpm
    • oscea
    • stuft2
    • pauldeden
    • mhailstone
    • gi60s
    • arasmus8
    • garygsc
    • byujol
    • martingarn
    • snelg
    • mzroth
    • byu-oit-bot