vss-web-extension-sdk - npm Package Compare versions

Comparing version 2.109.0 to 2.109.1

package.json

 {
   "name": "vss-web-extension-sdk",
-  "version": "2.109.0",
-  "description": "Visual Studio Services Client SDK. JavaScript library for Visual Studio Team Services extensions.",
+  "version": "2.109.1",
+  "description": "Visual Studio Team Services web extension JavaScript library and types.",
   "repository": {
@@ -6,0 +6,0 @@ "type": "git",

README.md

@@ -9,7 +9,7 @@ # Visual Studio Services Web Extension SDK
 
-> A previous version of the SDK was named ```vss-sdk``. Make sure to switch to the new `vss-web-extension-sdk` name.
+> A previous version of the SDK was named `vss-sdk`. Make sure to switch to the new `vss-web-extension-sdk` name.
 
 ## Get the SDK
 
-1. [Download](https://nodejs.org/en/download/) and install Node.js
+1. Download and install [Node.js]((https://nodejs.org/en/download/))
 2. Run `npm install vss-web-extension-sdk` from the root of your extension project
@@ -19,3 +19,3 @@
 
-### Add script to HTML page
+### Include the SDK script on your page
 
@@ -28,3 +28,3 @@ If you are developing a web extension, you will need to reference the SDK script from your HTML pages. For example:
 
-To ensure the SDK is included with your extension package, update your extension manifest (typically `vss-extension.json`) with a new `files` entry:
+To ensure the SDK script is packaged with your extension, update your extension manifest (typically `vss-extension.json`) and add a new entry to `files`:
 
@@ -34,5 +34,5 @@ ```
 	"files": [{
-		"path": "node_modules/vss-web-extension-sdk/lib/VSS.SDK.min.js",
+		"path": "node_modules/vss-web-extension-sdk/lib"",
 		"addressable": true,
-		"partName": "lib/VSS.SDK.min.js"
+		"packagePath": "lib"
 	}]
@@ -42,8 +42,9 @@ }
 
-## Use the SDK
+Note: setting `packagePath` is optional, but results in a simpler path for referencing the SDK script from your HTML pages. Not setting a part name would have required you to reference the full path in your `<script>` tag (`src="node_modules/vss-web-extension-sdk/lib/VSS.SDK.min.js"`)
 
-To initialize the SDK from your HTML page you have two options. 
 
- 1. Implicit handshake (simplest)
- 
+## Use the SDK 
+
+From your web extension's HTML page, include and initialize the VSS SDK like this:
+
  	```html
@@ -66,46 +67,27 @@ <script>
       
- 2. Explicit handshake
- 
-    ```html
-       <script>
-	  // Initialize with explicitNotifyLoaded set to true 
-	  VSS.init({
-          explicitNotifyLoaded: true,
-		  usePlatformScripts: true, 
-		  usePlatformStyles: true
-	  });
-      
-         // Perform some async operation here
-         doSomeAsyncStuff().then(
-            function(result) {
-              // Succeeded
-              VSS.notifyLoadSucceeded();
-              
-              // Start using VSS
-            },
-            function(error) {
-              // Failed
-              VSS.notifyLoadFailed(error);
-            }
-	 );
-      </script>
-    ```
-
 Full API reference of VSS.SDK.js can be found at [Core Client SDK](https://www.visualstudio.com/en-us/integrate/extensions/reference/client/core-sdk) page.
 
 ## Types
- * Types of VSS.SDK.js, controls and client services are available in typings/vss.d.ts. 
- * REST Client types for VSTS are available in typings/tfs.d.ts
- * REST Client and extensibility types for Release Management are available in typings/rmo.d.ts
- 
-### Dependencies
 
-Dependency graph for the types:
+Type definitions are provided for:
 
+ * UI controls and client services (see `typings/vss.d.ts`)
+ * REST clients and contracts for Build, Work, and Code (see `typings/tfs.d.ts`)
+ * REST clients and contracts for Release Management (see `typings/rmo.d.ts`)
+
+Dependency graph:
+
 ![Dependency Graph](img/dependencies.png)
  
-### Consuming the Types
+### Consuming the types
 
-You only need to add below line to the top of your TypeScript file:
+From a [TypeScript](https://www.typescriptlang.org) 2.0 or later project:
 
+1. Install the `vss-web-extension-sdk` module (see above)
+2. Update your `tfsconfig.json` project file to set ```"moduleResolution": "node"```
+
+See [TypeScript Module Resolution](https://www.typescriptlang.org/docs/handbook/module-resolution.html) for more details.
+
+You can explicitly reference the types at the top of your TypeScript file with:
+
 ```
@@ -115,6 +97,156 @@ /// <reference types="vss-web-extension-sdk" />
 
-Make sure that you specify ```"moduleResolution": "node"``` in your tsconfig.json file.
+## Organizing your web extension project
 
+If you are developing a web extension for Visual Studio Team Service using TypeScript, we recommend the following organization:
+
+### Project structure
+
+```
+ |-- src
+     |-- my-module
+         |-- a.ts
+         |-- b.ts
+ |-- static
+     |-- css
+         |-- main.css
+     |-- images
+         |-- logo.png
+     |-- my-hub.html
+ |-- vss-extension.json
+ |-- package.json
+ |-- tsconfig.json
+``` 
+
+1. TypeScript source files are placed in `src` (under one or more module folders).
+2. Static content (CSS, images, HTML pages, etc) are placed in `static`. This makes it easy to include all static files in your extension package.
+
+### TypeScript project file (`tsconfig.json`)
+
+Defines the options for compiling your TypeScript files.
+
+```json
+{
+    "compilerOptions": {
+        "module": "amd",
+        "moduleResolution": "node",
+        "target": "es5",
+	"rootDir": "src/",
+        "outDir": "dist/",
+        "types": [
+            "vss-web-extension-sdk"
+        ]	
+    },
+    "files": [
+        "src/my-module/a.ts",
+        "src/my-module/b.ts"
+    ]
+}
+```
+
+1. After compiling (`tsc -p .`), the resulting .js files are placed in `dist`. For example, `dist/my-module/a.js`.
+2. If your extension directly uses types from other @types modules, you will want to list them within `types`. See [@types](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
+
+Learn more about [tsconfig.json](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html)
+
+### NPM package manifest (`package.json`)
+
+Declares the libraries (like the vss-web-extension-sdk) required to compile, package, and use your extension.
+
+```
+{
+  /* other details like ID, version, etc are omitted */
+  
+  "scripts": {
+    "build": "tsc -p .",
+    "postbuild": "npm run package",
+    "package": "tfx extension create",
+    "clean": "rimraf ./dist && rimraf ./*.vsix"
+  },
+  "devDependencies": {
+    "rimraf": "^2.5.4",
+    "tfx-cli": "^0.3.45",
+    "typescript": "^2.1.4"
+  },
+  "dependencies": {
+    "@types/jquery": "^2.0.34",
+    "@types/q": "0.0.32",
+    "vss-web-extension-sdk": "^2.109.0"
+  }
+}
+```
+
+1. `scripts` provides a convenient way to define common operations that you want to perform on your project, like compiling and package. For example, to build (compile) and package your extension, run: `npm run build`. This runs `build` and `postbuild`. If you make a change that doesn't require compiling, you can package by simply running `npm run package`. 
+2. The dependencies on the @types for `jquery` and `q` are only necessary if your TypeScript code is directly referencing either of these types.
+
+Learn more about [package.json](https://docs.npmjs.com/files/package.json)
+
+### Extension manifest (`vss-extension.json`)
+
+```
+{
+    /* details omitted */
+    "files": [
+        {
+            "path": "dist",
+            "addressable": true,
+            "packagePath": "/"
+        },
+        {
+            "path": "static",
+            "addressable": true,
+            "packagePath": "/"
+        },
+        {
+            "path": "node_modules/vss-web-extension-sdk/lib",
+            "addressable": true,
+            "packagePath": "lib"
+        }
+    ],
+    "contributions": [
+        {
+            "id": "my-hub,
+            "type": "ms.vss-web.hub",
+            "properties": {
+                "name": "Hub",
+                "uri": "my-hub.html"
+            }
+        }
+    ]
+}
+```
+
+1. Compiled JavaScript files (placed into `dist`) will get packaged at the root of the extension (along with HTML, CSS, and images files).
+2. The `VSS.SDK.js` scripts (preferenced from your HTML pages) are placed under `lib` in the resulting extension package. 
+
+Learn more about the [extension manifest](https://www.visualstudio.com/en-us/docs/integrate/extensions/develop/manifest).
+
+### Any HTML page
+
+```html
+
+<head>
+   <script src="lib/VSS.SDK.min.js"></script>
+</head>
+
+<body>
+
+ <script type="text/javascript">
+
+        // Initialize the VSS sdk
+        VSS.init({
+            usePlatformScripts: true,
+            usePlatformStyles: true
+        });
+	
+	VSS.require(["my-module/a"], function (a) { 
+	    ...
+	});
+
+ </script>
+
+</body>
+```
+
 ## Code of Conduct
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[e-mail]](mailto:[e-mail]) with any additional questions or comments.

No alert changes

Improved metrics

Total package byte prevSize

1848268

increased by0.22%

Number of lines in readme file

246

increased by115.79%

No dependency changes