CONTRIBUTING.md

Contributing

There are several ways in which you can contribute to the project:

1. Log bugs or file feature suggestions. To do this, simply file the bugs/suggestions in the Issues tab on GitHub for this project.
2. Code samples. To suggest edits to existing samples, or to suggest your own, please submit a pull request against the Samples repo: https://github.com/OfficeDev/office-js-snippets.
3. Translations. In addition to English, we now support German, courtesy of a community member who liked Script Lab so much that he decided to translate it into his native language (and blazed the way for how to do translations in general)! Translating to other languages should now be pretty simple. Please see "TRANSLATING.md" for more details.
4. Bug-fix/feature contributions. If you have features or bug fixes that you'd like to see incorporated into the playground, just send us your pull request!

Running the playground from source

Prereq:

• Download & Install Visual Studio Code. https://code.visualstudio.com/. If you don't have a recent version, please update to latest (1.11 at time of writing)
  • I would also recommend installing the TSLint extension, which adds lint warnings straight into the editor.
• Download & install Node (version 6.11+, or 8.9+) https://nodejs.org/en.
• Download & install Python 2.X, necessary for one of the dependencies (node-sass). Download from https://www.python.org/download/releases/2.7.3/
• Download & install Yarn, for use as an alternative for npm install. Download from https://yarnpkg.com/en/docs/install (or bootstrap Yarn installation by running once npm install -g yarn). The documentation also describes why Yarn is preferable to npm install.

Note: the installation of Node JS and Yarn add paths to your operating system's PATH variable. Therefore, in some cases you may log off and log in from your System to get Node JS and Yarn work withing Visual Studio Code.

Build steps:

1. Clone the repo

2. Open the root of the repository with VS Code. (File --> Open Folder...)
   
   

3. Open the terminal from within VS Code (View --> Integrated Terminal)
   
   

4. In the terminal, type in yarn install and wait for all of the packages to be downloaded (this may take a few minutes). The command prompt will return the control back to you once it's done.

5. Run npm start in the terminal (or ctrl+shift+b and select start in the dropdown). The process may pause for a few seconds, and you may see messages like "compilation complete"; but don't believe it! You'll know that it's finally done when the web browser launches to https://localhost:3000, and when you see the following appear in the terminal:

[BS] Proxying: https://localhost:3100
[BS] Access URLs:
 --------------------------------------
       Local: https://localhost:3000
    External: https://10.82.217.77:3000
 --------------------------------------
          UI: http://localhost:3001
 UI External: http://10.82.217.77:3001
 --------------------------------------

6. Importantly, once the npm start has completed and you see the message above, start the runner (server) by pressing F5 within VS Code. Failure to do this will cause the "run" button to lead to an error (since the server, which is where the "run" code is running, is offline). Ditto for auth, export, and other scenarios.

7. Trust the certificates for both https://localhost:3000, https://localhost:3100, and https://localhost:3200. For purposes of running add-ins on a PC, do this within Internet Explorer. See the gif below for a step-by-step animation:

.

The website is now running. To try it out in an Add-in, see the next section.

Note: To stop debugging, first press the "stop" button on the debugger (shift + F5). You will see an error on the server terminal window ([nodemon] app crashed - waiting for file changes before starting...); that's ok, just close that terminal instance (trash icon on top-right of terminal). If you want to restart debugging later, just re-press F5 again.

Troubleshooting:

1. If you need to configure BrowserSync settings (including making it stop syncing automatically, if you get into a recursive reload loop...), go to http://localhost:3001/sync-options.

2. If you get an error like modules 14/14 modules 0 activeError: listen EADDRINUSE 127.0.0.1:3100:

• In a git bash shell, type out netstat -a -o | grep 3100 (or whatever the port number is) You will get a response like: TCP 127.0.0.1:3100 <computer-name>:0 LISTENING 12220
• In a regular command prompt, run taskkill /pid 12220 /F (where 12220 is the process ID from rightmost column)

Testing inside of an add-in

1. Locate the add-in manifest (which you'll find in the manifests folder in the root of the repo). For purposes of running against localhost, use script-lab-local.xml.

2. Sideload the manifest into your office host application. Simplest option, on the desktop (tested on PC), is to run npm run sideload:excel. Otherwise, see https://aka.ms/sideload-addins, which includes instructions and a step-by-step video for sideloading on the desktop, as well as links for the other platforms.

General structure

The project consists of two separate components: the client (editor) and the server (runner). When run -- both on a dev machine, and in production -- they run on two separate URLs. That way, a running snippet can never get the localStorage data (snippets, auth tokens, etc.) of the actual playground.

At the root level of the repo, the folders of interest (and skipping over the others) are:

• client: This is the playground editor UI.
• config: Configuration related to webpack & deployment.
• dist: The generated files for client and server (it has subfolders for each), which are the compiled and minified html/js/css/etc. If you do a npm run build, you will get the full dist folder; otherwise, with an npm start, you'll only get a partial one (since client files will mostly be served from in-memory).
• manifests: Add-in manifests (both localhost and production) for side-loading the Add-in into Office applications.
• node_modules: The folder with all the node module dependencies that get installed as part of yarn install.
• server: A stateless Node backend that receives a POST request with the snippet's HTML, TypeScript, CSS, and Libraries, and creates a web-browser-servable web page out of them. The server makes extensive use of Handlebars.js for templates, which are located in the server/templates directory.
• typings: Type definitions for a few of the libraries.

There are also files related to Azure deployment, git ignores, a Travis configuration for continuous-integration, a package.json with the project's metadata, TypeScript configuration files for client and server, a linter configuration, and etc. And of course, the project's README.

Enabling auth for local testing (optional, if debugging auth-related code)

1. Go to https://github.com/settings/developers, and click "Register new application" if you haven't done it before for your own dev copy of ScriptLab.
2. Give it a name like "ScriptLab Local Dev", with a Homepage and Auth callback URL of https://localhost:3000.
3. In config/env.config.js, find the const config = { ... line, and under local: { ..., fill in the client ID and client secret
4. If the site is running, re-start it and do a new npm start. Incremental compilation is not enough for these changes. Note, too, that you need both the site and the server (F5) running to make auth work.
5. Once you are done with your testing, be sure to undo both changes!.

Manual-testing scenarios

Please see "TESTING.md".

Tips & tricks

• There are two package.json files, one at the global level (for the client), and one inside of src\server. This can lead to differences in behavior between localhost and the deployed site, so be careful (e.g., if add one dependency in one place that should be shared, add it in both!). Their version numbers should also be bumped in synchrony.
• On IE, console.log in the runner won't display anything in FirebugLite if F12 tools are open. It works fine if they're closed.