# Add Skyline to your Stack

Installing Skyline into a brand new project? These instructions will help get you started.

Prerequisites
Installing Skyline
Installing Icons
- Set Up SVG Loader
- Install Icon Packages
Installing Illustrations
Importing Styles
- Default Styling
- Importing Utilities and Components
PostCSS Configuration
- Examples in Webpack
- Examples in Gulp
Update Skyline
Importing Vue
- i18n support
- Transpiling and Polyfilling
Core Technologies

# Prerequisites

Your computer is connected to the Benevity VPN (opens new window).
Your computer has the latest Node LTS installed (opens new window).
Your project is setup to use Sass (opens new window).
Your project is using Webpack (opens new window)
- If you have no build pipeline in place, check out our how-to on making a simple build script
Your computer has Yarn v1 installed (opens new window)
- (optional, but all examples in this site will use Yarn as the Node package manager).
Run commands from your project root, not your user root.
A familiarity with using your command line.
A thirst for beauty in this world.

# Installing Skyline

To install Skyline in your project you must use Benevity's private npm registry.
- ```
 echo "registry=https://artifactory.benevity-shared.org/api/npm/product-npm-prod/" >> .npmrc
```
- This will point your package manager to Benevity's private NPM which will give you access to Skyline
Add the following Skyline packages to your node_modules folder
- yarn add @skyline/scss
- yarn add @skyline/vue @vue/composition-api @popperjs/core vue-i18n@^8.0.0
Import the styles and components into your project.
Install icon libraries that you want to use in your project.
Install the illustrations package if you want to use illustration components.

# Installing Icons

# Set Up SVG Loader

First, you need to configure vue-svg-loader (opens new window) in webpack.

vue-svg-loader is responsible for transforming raw SVG files into Vue compatible JavaScript objects. Without this, webpack doesn't know what to do with SVGs when inserted into Vue templates.

# Install Icon Packages

The majority of the icons used at Benevity come from FontAwesome, but there are also custom Skyline icons available:

yarn add @fortawesome/fontawesome-pro
yarn add @skyline/icons

# Installing Illustrations

Illustrations are available for use as Vue components via the illustrations package.

Add @skyline/illustrations as a dependency

$ yarn install @skyline/illustrations

Import the package's CSS:

// main.js
...
import '@skyline/illustrations/dist/index.css'
...

Use them in your Vue components!

vue-svg-loader must also be installed and configured in your project.

# Importing Styles

# Default Styling

To "bootstrap" your application with default styling (baseline fonts, sizes, etc.), import the bootstrap file into your application's main SCSS file:

@import '~@skyline/scss/src/bootstrap';

NOTE: Importing the bootstrap file into a legacy application may have unexpected results due to styling collisions.

# Importing Utilities and Components

Add @import '~@skyline/scss/src/core/UI.required' to the top of your main SCSS file
- If you don't include this file, nothing in Skyline will work.
- If you're importing the bootstrap file, you don't need to add the UI.required file. It's already included.
- The UI.required import will add all functions, mixins, and variables that Skyline needs to operate.
- It does not export any css on its own, so it is safe to include multiple times.
Consider what Skyline configuration options might be appropriate for your project.
Import any other components or utility files on on as-needed basis. Here is an example from the Grants Laravel project (opens new window).

# PostCSS Configuration

Skyline SCSS requires you to properly configure running PostCSS on your projects' CSS to account for legacy browser CSS prefixes (mostly an IE 11 problem).

Skyline only provides CSS as output by our SCSS mixins and functions. PostCSS runs after SCSS has been compiled to CSS. So features like "autoprefixer" (which PostCSS Preset Env runs for you) have to be run on the consumers' end.

PostCSS Preset Env (opens new window) lets you convert modern CSS into something most browsers can understand, determining the polyfills you need based on your targeted browsers or runtime environments.

For Skyline's needs PostCSS Preset Env can be configured with its default settings (opens new window) (unless your project has other needs)
Make sure you have configured your browser support (opens new window) to include IE 11

# Examples in Webpack

# Examples in Gulp

# Update Skyline

You should update early and often as Skyline releases new features. You can update using yarn upgrade-interactive and choose the new available package under @skyline/scss
- Skyline is backwards compatible and adheres to the semantic versioning scheme (opens new window).
- If Skyline releases a breaking change, we'll increase the major version by one (eg. 2.0.0 -> 3.0.0). Upgrade instructions will be shared in slack (opens new window).
Join the #skyline-design-system (opens new window) Slack channel to get notifications when we make an update.

# Importing Vue

Skyline Vue provides a plugin which globally registers all Skyline components into your Vue project. You do not need to import them into every file.

Import the plugin and the composition API plugin (opens new window) into your main entrypoint for Vue:

// main.js or whatever your entry point file for Vue is called

import Vue from 'vue'
// This is required as it is a peer dependency of the Vue components.
import VueCompositionAPI from '@vue/composition-api'
// This is required otherwise the Vue Skyline components will not be styled.
import '@skyline/vue/dist/skyline.css'
import Skyline from '@skyline/vue'
import vueI18n from 'vue-i18n'
Vue.use(VueCompositionAPI)
// Configuring vue-i18n is going to be very project specific so we are leaving
// the specifics of this up to implementation.
Vue.use(vueI18n)
Vue.use(Skyline)

If your project needs IE 11 support, your project is responsible for making sure these components will work. Continue below to the transpiling and polyfilling section to learn how.

# i18n support

i18n = Internationalization (i followed by 18 letters ending in n)

While Skyline is agnostic to the content you use to populate its components, a small number of Skyline components do contain readable text and accessible text strings that wouldn't make sense for a consuming application to provide.

Skyline requires that vue-i18n (opens new window) to be available/installed on the Vue object.

Even if your project currently has no translation concerns, we have to support multiple languages for the projects that do.

If your project currently has no translation concerns you can install and configure vue-i18n with the en locale which will give you our english translations by default.

// your entry point js file for your Vue App
...
import vueI18n from 'vue-i18n'

Vue.use(vueI18n)

const i18n = new VueI18n({ locale: 'en' }) // This value could come from a vuex store or somewhere else that is dynamic.

new Vue({
  render: h => h(App),
  i18n, // Attach the configured vue-i18n object to the Vue app.
}).$mount("#app");

# Transpiling and Polyfilling

Skyline Vue does not transpile or polyfill its library bundle. We are leaving this up to library consumers to transpile and polyfill this library for IE 11 support.

We made this choice because Polyfilling library code results in unnecessary code bloat, mismatched polyfills and experience breaking. Additionally, trying to debug JavaScript errors for different types of polyfills between the consuming and library code is a challenge.

We ship ES 6 library code to account for a future without IE 11 support.

Since babel typically does not transpile node_module code you'll need to opt-into babel transpiling Skyline.

This can be done by modifying your babel configs' exclude key

// babel.config.js

// Example of using RegEx to include some `node_module` packages that need to be
// transpiled by babel.
// There are other ways of doing this but we cannot account for every type of config.
const transpileDependencies = [
  'lodash-es',
  '@skyline/vue'
]
...
exclude: new RegExp(`node_modules/(?!(${transpileDependencies.join('|')})/)`)
...