Chris OBrien - Pitfalls when developing with the SharePoint Framework (SPFx)
Download as PPTX, PDF0 likes9,899 views
The document discusses various pitfalls when developing with the SharePoint Framework (SPFx), highlighting issues related to dependencies, code reuse, async programming, and deployment challenges. Key recommendations include using npm for dependency management, creating modules for code reuse, understanding Office UI Fabric components, and avoiding accidental bundling of libraries. The presentation emphasizes the importance of adopting best practices to ensure effective and manageable SPFx development.
![Recommendations – code re-use
Pitfall How More reading
Copy/pasting JS code into
each project
Create modules for existing code
Consider module strategy:
• npm install [filepath]
• npm link (for “parallel dev” of client and utility
code)
• Use of npm private packages etc.
http://nicksellen.co.
uk/2015/04/17/ho
w-to-manage-
private-npm-
modules.html
http://stackoverflo
w.com/questions/2
1233108/cross-
project-references-
between-two-
projects](https://image.slidesharecdn.com/chrisobrien-pitfallswhendevelopingwiththesharepointframework-slideshare-171129075529/85/Chris-OBrien-Pitfalls-when-developing-with-the-SharePoint-Framework-SPFx-23-320.jpg)
Chris OBrien - Pitfalls when developing with the SharePoint Framework (SPFx)
- 1. Pitfalls when developing with the SharePoint Framework (SPFx) Chris O’Brien (MVP) Independent/Content and Code, UK Add Speaker Photo here
- 2. Notes on this presentation If you have previously seen this presentation/slide deck before, note the following updates: Content Slides Pitfalls around Office UI Fabric 27-30 Pitfalls around calling the Microsoft Graph or custom APIs secured with Azure Active Directory 31-35 Use of SPFx component bundles 40-42
- 4. Fundamentals – how it all works Packages installed/updated using npm • .NET analogy = NuGet Dependent JS libraries stored in node_modules • .NET analogy = the BIN directory • Gets bundled/deployed with your app Package.json records your top-level dependencies • .NET analogy = packages.config • Allows other devs to build app from source control • N.B. Each dependency may have IT’S OWN dependencies and package.json
- 5. COB App - node_modules - jQuery - node_modules - cache-swap - node_modules - React - node_modules …… Simplified node_modules hierarchy
- 6. Fundamentals - how to add a library Use npm install command e.g: npm install jquery Installs library to your app (in node_modules) Important parameter: --save OR --save-exact Usually add TypeScript typings (for auto-complete) npm install @types/jquery -–save
- 7. Understanding package.json dependencies node • Lists all 3rd party libraries needed to run devDependencies node • Lists all 3rd party libraries needed to develop/build
- 8. Semantic versioning (semver) Example Known as Meaning ^1.2.1 Caret dependency Greater than or equal to 1.2.1, but less than 2.0.0 ~1.2.1 Tilde dependency Greater than or equal to 1.2.1, but less than 1.3.0 1.2.1 Exact dependency 1.2.1 only Fundamentals 3 part version number – e.g. 1.0.0 Major.Minor.Patch Major = breaking change/substantial differences Minor = non-breaking e.g. new methods Patch = no interface changes e.g. optimisations, documentation
- 9. Versioning/dependency pitfalls Using caret dependencies (the default) Not specifying – save on npm install Dev: Not locking dependencies down Shipping: Will change in npm 5!
- 11. Dependencies and shipping The problem – “dependency float” • Your app has many JS dependencies (the node_modules tree) • node_modules should not be checked-in • Different version somewhere in tree -> Broken app The solution – npm shrinkwrap • Generates npm-shrinkwrap.json file Critical to getting a “100% reproducible build” • Locks down dependencies – for entire node_modules tree
- 12. npm shrinkwrap Tip - check-in npm-shrinkwrap.json for each shipped release • Allows exact build to be recreated • Allows other devs to build exact app from source control Better than save-exact – deals with full dependency tree • save-exact only deals with top-level dependencies
- 14. Remember the rule: = OK ^ = Not OK
- 15. Recommendations – versioning etc. Pitfall How avoided More reading Avoid dependency issues in dev Ensure devs *save* packages properly – use npm install --save/--save-exact. Consider custom .npmrc file across team http://cob- sp.com/2fOtApJ Avoid dependency issues when shipping Use npm shrinkwrap for each release https://docs.npmjs. com/cli/shrinkwrap
- 17. Code re-use pitfall Copy/pasting JS code into each app, because not clear how to re-use properly
- 18. Re-using existing JS code Create a module for your code • Expose each method with exports statement: module.exports = { CheckRealValue: COB.CORE.Utilities.CheckRealValue, StringIsEmpty: COB.CORE.Utilities.StringIsEmpty } Create package.json file • Specify entry point (file)
- 19. Re-using existing JS code Access module with ‘require’ • var cobUtil = require('cob-utility') • cobUtil.StringIsEmpty("foo");
- 21. So, now you have a module. How to include/reference that?
- 22. Some popular options Use npm LOCAL packages • Install from file path (COPY) or use NPM LINK Use node_modules higher up filesystem • Take advantage of “recurse upwards” approach of npm- See http://cob- sp.com/2eXDJOI Use private package hosting • npm private packages - $7 pm/user • VSTO private hosting - $4 pm/user Also consider: https://www.visualstudio.co m/en- us/docs/package/install
- 23. Recommendations – code re-use Pitfall How More reading Copy/pasting JS code into each project Create modules for existing code Consider module strategy: • npm install [filepath] • npm link (for “parallel dev” of client and utility code) • Use of npm private packages etc. http://nicksellen.co. uk/2015/04/17/ho w-to-manage- private-npm- modules.html http://stackoverflo w.com/questions/2 1233108/cross- project-references- between-two- projects
- 25. SPFX coding pitfalls Dealing with async code/ promises Calling the Microsoft Graph (permutations) Calling secure APIs (AAD)Office UI Fabric Adding a library TypeScript issues
- 26. Pitfall – Office UI Fabric issues Problem: You want to use Fabric but are confused..
- 27. Office UI Fabric • Office UI Fabric Core a.k.a. Fabric Core - this is a set of core styles, typography, a responsive grid, animations, icons, and other fundamental building blocks of the overall design language. • Office UI Fabric React a.k.a. Fabric React - this package contains a set of React components built on top of the Fabric design language.
- 28. Pitfall – Office UI Fabric issues Problem: You want to use Fabric but are confused.. Solution: • To use Fabric Core easily, use SPFx v1.3.4 or later ( • Using React? Can use Fabric React components – use individual static links (for bundle size) Key npm packages: • office-ui-fabric- react • @microsoft/sp- office-ui-fabric- core (new)
- 29. Correct use of Fabric React (bundling approach) WARNING – React styles are bundled with EACH web part in this approach. Mitigate with SPFx component bundles if you need to (e.g. expecting many of your web parts on page). See http://cob-sp.com/2hPVmUc
- 30. Pitfall – calling the Graph/custom APIs Problem: You need to call the Graph or a custom API from SPFx (i.e. AAD-secured) Solution: • Understand today’s options: • GraphHttpClient (limited scenarios!) • AAD app + adal.js • AAD app + SPO auth cookie/IFrame approach • Understand a future option: • AAD app + tell SPFx to trust it
- 31. Graph/custom API permutations - GraphHttpClient - or more likely, use of adal.js Calling the Graph from client-side - adal.js - SPO auth cookie/IFrame Calling custom API (AAD) from client-side •- adal.js from client (SPO auth cookie approach gives token which cannot be used with Graph) - adal.NET within custom API OR - New Azure Functions bindings (preview – can’t get to work!) - Use of both “on behalf of user” and “app-only” Calling custom API (AAD) from client-side which calls the Graph Reference: Connect to API secured with AAD - http://cob- sp.com/SPFx-AAD
- 32. Cheat sheet - custom APIs/Azure Functions with AAD ADAL.js • CORS – define rule for each calling page • Code - Ensure asking for token for your resource (AAD client ID) SPO auth cookie approach • Empty CORS rules • Code: • Pass “credentials” : “include” header, and sure API/Function can receive.. • IFrame onto Function URL Reference: Connect to API secured with AAD - http://cob- sp.com/SPFx-AAD CONSIDER: • Each web part/extension on page must sign-in • AAD reply URL needed for each page with WP (max 10!) CONSIDER: • Sign-in applies to entire page/session • Cannot access user identity (app-only)
- 33. Future option – Graph/customAPIs Graph - Specify additional permission scopes for GraphHttpClient e.g. I’m OK with all SPFx web parts having access to more than Groups and Reports Your APIs/Azure Functions Specify additional custom APIs for same token Benefit – no need for sign-in button in your WP/extension Dev preview late 2017? { "WebApiPermissionRequest": { "ResourceId": “GUID goes here", "Scope": “GUID goes here", } "WebApiPermissionRequest": { "ResourceId": “GUID goes here", "Scope": “GUID goes here", } "WebApiPermissionRequest": { "ResourceId": “GUID goes here", "Scope": “GUID goes here", }
- 34. Recommendations – coding Pitfall How avoided More reading Office UI Fabric issues Get familiar with: • Fabric Core vs. Fabric React components • SPFx 1.3.4/sp-office-ui-fabric-core package • Using mixins in your SCSS http://cob-sp.com/SPFx- OUIF Graph/custom API issues Get familiar with: • Register AAD apps + adal.js • SPO auth cookie approach • Future SPFx option http://cob-sp.com/SPFx-AAD Async code issues Get familiar with: • Promises http://cob-sp.com/SPFX- Promises Security issues Avoid SPFX if sensitive data sent to client (page or JS) - use Add-in parts/IFrames if needed http://cob-sp.com/2ez9JNX
- 36. Pitfalls - deployment Accidentally bundling external libraries/frameworks Accidentally shipping a debug build Losing track of remote JS code
- 37. Bundling considerations Librariesare includedin your bundle BY DEFAULT Update config.json if (e.g.) jQuery should be referenced from CDN One bundleper web part BY DEFAULT - across your site 10 web parts = 10 different copies of jQuery being downloaded GUID in bundleURL is regeneratedon each build This is the versioning/cache-busting mechanism TIP – delete unused JS files from CDN to keep things tidy
- 39. Bundling – rule #1 “Externalise” where possible (CDN):
- 40. Bundling – rule #2 Ensure any libs you ARE bundling are consolidated (with SPFx component bundles): WP1 WP2 cob-bothWebParts.js
- 41. Recommendations – deployment Pitfall How avoided More reading Accidental bundling Ensure libs loaded externally where possible Update “externals” section of config.json Waldek - http://cob- sp.com/2frVMR3 Duplication of code in bundle Use SPFx component bundles Elio - http://cob- sp.com/SPFx- CompBundle Losing track of remote JS code • Proactively track CDN locations (e.g. Excel?) • Use SPCAF to help identify www.spcaf.com
- 42. Key take-aways It’s a new world, with different pitfalls! Recommendations: Get familiar with NPM especially Plan for code re-use (e.g. modules) if appropriate Practice “production” deployments Dependencies/versioning e.g. dependency float Coding e.g. OUIF, calling the Graph or custom APIs Deployment e.g. accidental bundling, duplication in bundle
- 43. Thank you!! Any questions? www.sharepointnutsandbolts.com
- 44. Bundling – how it goes wrong Perhaps a 2nd web part is added.. Some libraries are installed using npm (e.g. Angular)..
- 45. Bundling – how it goes wrong gulp bundle --ship gulp deploy-azure-storage gulp package-solution --ship SPFx deployment process:
- 46. Bundling – how it goes wrong App package added to App Catalog:
- 47. Bundling – done wrong