Debugging

With the release of 2.0 we wanted to enhance the debugging story for the library both when consuming it in other applications and working on library features. This page outlines debugging in various scenarios.

Debugging Library Features in Code using Node

The easiest way to debug the library when working on new features is using F5 in Visual Studio Code. This uses the launch.json file to build and run the library using debug/debug.ts as the program entry. You can add any number of files to this directory and they will be ignored by git, however the debug.ts file is not, so please ensure you don't commit any login information.

Setup settings.js

If you have not already you need to create a settings.js files by copying settings.example.js and renaming it. Then update the clientId, clientSecret, and siteUrl fields in the testing section.

Test your setup

If you hit F5 now you should be able to see the full response from getting the web's title in the internal console window. If not ensure that you have properly updated the settings file and registered the add-in perms correctly.

Create a debug module

Using example.ts as a reference create a debugging file in the debug folder, let's call it mydebug.ts and add this content:

// note use of relative paths to the modules
import pnp from "../src/pnp";
import { Logger, LogLevel, ConsoleListener } from "../src/utils/logging";
import { ListEnsureResult } from "../src/pnp";

export function MyDebug() {

    // run some debugging
    pnp.sp.web.lists.ensure("MyFirstList").then((list: ListEnsureResult) => {

        Logger.log({
            data: list.created,
            message: "Was list created?",
            level: LogLevel.Verbose
        });

        if (list.created) {

            Logger.log({
                data: list.data,
                message: "Raw data from list creation.",
                level: LogLevel.Verbose
            });

        } else {

            Logger.log({
                data: null,
                message: "List already created!",
                level: LogLevel.Verbose
            });
        }
    });
}

Update debug.ts to launch your module

First comment out the import for the default example and then add the import and function call for yours, the updated debug.ts should look like this:

// ...

// comment out the example
// import { Example } from "./example";
// Example();

import { MyDebug } from "./mydebug"
MyDebug();

// ...

Debug!

Place a break point within the promise resolution in your debug file and hit F5. Your module should be run and your break point hit. You can then examine the contents of the objects and see the run time state. Remember you can also set breakpoints within the src folder to see exactly how things are working during your debugging scenarios.

Next Steps

Using this pattern you can create and preserve multiple debugging scenarios in separate modules locally.

In Browser Debugging

With the 2.0 release we have improved the watch/serve features of the library to improve the debugging experience in the browser. The development server will run continuously until you cancel it (Ctrl + C) and watch the /src folder for any changes. So you can make updates to the library and then hit F5 in the browser to see your changes.

Start the local serve

gulp serve

Add reference to library

Within a SharePoint page add a script editor web part and then paste in the following code:

<script src="https://localhost:8080/assets/pnp.js"></script>
<script>
    alert($pnp.util.getRandomString(10));
</script>

You should see an alert with a random string.

Next Steps

You can make changes to the library and immediately see them reflected in the browser. Also, you can do more than just show an alert :)

Debugging in SPFx

If you are working with the library in the context of the SharePoint Framework and would like to debug your local changes in that context you can easily.

Add External Reference

Within the SharePoint Framework's config/config.js folder add an external reference to your locally served file:

"sp-pnp-js": "https://localhost:8080/assets/pnp.js"

Start Local Servers

Within the sp-pnp-js project start the local server

gulp serve

Within the SPFx project start the local server

gulp serve

This allows you to serve the local sp-pnp-js file directly to your local SPFx project so you can work with both directly. Additionally because source maps are available you will be able to debug both your SPFx code as well as the sp-pnp-js library.