Monday, July 24, 2017

SPFx: Sharing Modules between projects

This is something that is not covered all that much in SPFx talks I've been to, and is definitely something everyone should know how to do.

Imagine you have several SPFx projects, and they all need to connect to the same LOB system. Or maybe you are an ISV that needs to check for product licenses. Perhaps you have your own UI library that your company built and you need to use, or even just a few helper functions that you always wished were a part of the JavaScript language and hate that you have to re-write them every time.

In all these cases, you will end up with a bunch of code that you wish you could put in once place and reuse in several SPFx projects.

For the .Net developers out there - that would probably go into a DLL that you would reference from your other projects. Right?

But, how do you do it in SPFx?

Well, turns out there are MANY ways to do it, they are different, and not all of them would lead to a good practice or comfortable code management.

I won't list them all, of course, but will show you what I chose to do and share some of the considerations behind it.

Relative folder

I guess the easiest way to deal with it is to just place your code in a separate folder.
You will create a folder with your module name, say "shared-code".
Now, when you want to use it from different projects - all you got to do is import it from the relative folder path, for example:
import Utilities from '../../../../shared-code/Utilities';
Now, say you want to use TypeScript in your shared module. You will need to create a tsconfig.json file and complile the TS into JS files before you can use them.
Example of tsconfig.json I use:
{
  "compilerOptions": {
    "target": "es5",
    "forceConsistentCasingInFileNames": true,
    "module": "amd",
    "moduleResolution": "node",
    "declaration": true,
    "sourceMap": true,
    "experimentalDecorators": true,
    "types": [
      "es6-promise",
      "es6-collections"
    ]
  },
  "exclude": [
    "node_modules"
  ]
}

* notice I use module "amd". This is important if you later plan to load it as external from CDN and don't want it to register a global object.


And if you are using TypeScript, you probably would want to import some SPFx types and objects to work with, right? Since we don't have a package, you will have to manually add the npm packages for these using these commands:
    npm install @microsoft/sp-core-library@~1.1.0

    npm install @microsoft/sp-webpart-base@~1.1.1


Now, when your code is ready, simply run "tsc" in that folder to compile it to JavaScript and your are ready to go.

Advantages

Quick and easy. You can automate the tsc compiler task so it will be completely transparent to you.

Disadvantages


  1. Since we don't have a package, there is no way to trace versions.
  2. You cannot set package dependencies and restore them automatically with npm install later on.
  3. Also, you cannot mark it as external and load it from a CDN. It must be bundled with your web parts.

Separate Package

If you want to be able to use your shared module as a package, you will need to create a package definition file.
Luckily, NPM created a helper that does it for you.
Go back to your "shared-code" folder, and run "npm init" command. Follow the instructions to create a package definition file. While running npm init, a couple of notes to keep in mind:

  • Only lower case and - are supported.
  • Author needs to be in this format: name <email> (web site)
  • To specify a license file, set it to: "SEE LICENSE IN <filename>"
Once this is done you will have a new package.json file created in your folder. Open it.
You will see your have a version number here. Every time you make changes to your code, you should update the version number. This is whats telling "npm update" command when to update your package.
Also, if your are using TypeScript, you should add "typings" to your package definition file.
Now, we can add the 2 SPFx node modules as proper dependencies instead of installing them manually. Add "dependencies" to the end of your package.json file with the 2 packages. Your file should look like this:
{
  "name": "shared-code",
  "version": "1.0.0",
  "description": "my shared code",
  "main": "utilities.js",
  "typings": "utilities.d.ts",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "KWizCom  (http://www.kwizcom.com)",
  "license": "SEE LICENSE IN license.md",
  "dependencies": {
    "@microsoft/sp-core-library": "~1.1.0",
    "@microsoft/sp-webpart-base": "~1.1.1"
  }
}

Once you are done, save the file. You can now install dependencies using "npm install", and get updates using "npm update".



* You might also want to create a license file if you specified one during the npm init.

Last, you need to publish your package. Either you commit to GitHub or publish to npm using "npm publish" - you will be able to reference your package by name from that source.

When you want to use it in your SPFx projects, you can add it as a dependency to your package.json file:
"dependencies": {
  "@microsoft/sp-core-library": "~1.1.0",
  "@microsoft/sp-webpart-base": "~1.1.1",
  ...
  "shared-code": "*"
}

Advantages


  1. Having a package helps keep track on dependencies inside your package.
  2. A package file keeps track of versioning.
  3. When using a package, it is added as a dependency just like any other library you are using.
  4. You can mark packages as external in config/config.json file, to load it from a CDN instead of bundling it into your JS file:
"externals": {
  "shared-code": "https://apps.kwizcom.com/shared-code/utilities.js"
},

Disadvantages

You have to publish this package to a different project/source (npm or GitHub or both).
This makes tracking and managing your code a bit more complex, if you are not already using that system for your source control.

Separate local package

Much like the published npm package, you can follow all steps except - don't publish it to npm/GitHub separatly.
I keep all my projects including the shared packages in the same source control system, in the same folder structure.
When I set up the dependencies for my packages, since I store them all in the same source control and they will be available locally together - I can specify a local folder relative path to that package.
In the package.json file, I set it up as:
   "shared-code": "file:../shared-code"

Advantages

I find this to be the easiest way in my environment, since I don't have to keep track of two different systems or projects. When I sync changes from the server, I get updates for all projects and for my shared module at the same time.

Disadvantages

In my case, that works best. But if your projects or source control system does not set up to keep the folder structure and get updates from all projects at the same time - you might want to get your package from npm or GitHub. That's because if you ever get a new PC and run "npm install" it might not be able to find and get this shared package from a local folder if you didn't get it previously.

Type mismatch

There is one issue you might notice when working with TypeScript.
You might get an error reporting a type mismatch between the same object. For example, when you send your web part context into a function in shared-code, it might say the objects do not match.
This is caused because the SPFx libraries are not installed globally, so each project has its own definition of these objects. A simple solution is to send it as type any, I will discuss a better resolution for this conflict in a later post.

Closing

I know this sounds complicated, and honestly it is much more complicated than it should be. In C#, building a dll library was a simple common task.
But, like everything else, once you get used to it - it is not that bad.
(If you enjoy typing console commands and editing json files...)

Hope this helped you make sense of the procedure better, I didn't find a simple clear instructions on this topic yet so I thought it is worth sharing.

Tuesday, July 18, 2017

Debugging SPFx using VSCode - multiple projects in sub folders

I've been quite happy with Chrome TS debugging capabilities, honestly, so I never really cared to try VSCode debugging until now.

Thing is, I've been working on my "SPFx from an ISV point of view" session and wanted to cover all options in my presentation, so I thought I should probably set it up and write about it.

Finding the instructions was simple enough, and the guys @msft did a good job detailing how its done here.

However, in my situation (for reasons I will share later on) we have decided to create a root SPFx folder and place our projects as sub folders under that root folder. So, when I open my VSCode, the root folder is not my SPFx project root.

That folder structure broke the debugging configuration file and it couldn't find any maps files.

I could not find any documentation on the different properties in the JSON config file, but it was simple enough to understand.

After playing around with it for a bit, I figured the debugger used the "webRoot" property to find the source files inside VSCode.

All I needed to do is change:

"webRoot": "${workspaceRoot}"

to:

"webRoot": "${workspaceRoot}/DVP"

and my debugger connected correctly and started working.

Why do I use sub folders? That - I will explain in a later post, or in my talk at the end of the month @SPSNYC.

Friday, June 23, 2017

SPFx workbench certificate error in Chrome after v58

Anyone using the workbench in chrome either already noticed or will very soon that the workbench is no longer working as of update 58 of chrome.

If you use the local workbench - no problem. you will see a clear certificate error, and you will be able to proceed with an "unsafe" certificate.

But, if you try to use the online workbench (at /_layouts/15/workbench.aspx ) things will be a bit more tricky...

See, you won't get a certificate error right away. Instead your online workbench (which is on your SharePoint site's certificate, which is perfectly valid) will load up correctly and will show the message as if you are not running gulp serve:


Why? If you open the dev tools you will see under network that all the requests to localhost were blocked due to the same issue with the bad certificate.

There are 2 things you can do:

Temporary fix:

Browse to the local workbench in chrome, select to proceed with the unsafe certificate. This will allow chrome to access your localhost.
Now, your online workbench should also start working as expected.
This should last until you close your browser.

Permanent fix:

It seems a new certificate was created that works with Chrome, as a part of the "sp-build-web" npm package v1.0.1
(Thanks Ian, @iclanton read more here)

SPFx GA points to v1.0.0 which doesn't include the new certificate.

To make the fix permanent, here are the exact steps I took (after a lot of tries and other variations that just led to more trouble...):
  1. edit package.json and change ONLY the sp-build-web version to 1.0.1 (Not to the latest, as gulp serve will stop working if you do)
  2. delete node_modules folder (npm install will fail if you don't delete the entire folder)
  3. run npm install
  4. run gulp untrust-dev-cert (you should be prompted to delete a certificate)
  5. run gulp trust-dev-cert (you should be prompted to install a certificate)
  6. run gulp serve
Now, your local or online workbench should work as expected.

This took way longer than I expected, since any single different thing I tried resulted in either a broken project or npm install failure...

Good luck!