Add SpaServices with ASP.NET Core doc #3563
Conversation
There was a problem hiding this comment.
@scottaddie @tdykstra it wouldn't let me make a new PR of this PR, I'd like to figure that out. So I had to commit into Scott's branch. See 573272c and let me know where I was too aggressive.
@tdykstra point out any changes that should be backed out
| --- | ||
| # Using SpaServices for Creating Single Page Applications with ASP.NET Core | ||
|
|
||
| By [Scott Addie](https://github.com/scottaddie) |
There was a problem hiding this comment.
can you add the other guy - if you got anything from his work.
|
|
||
| [!code-javascript[Main](../client-side/spa-services/sample/SpaServicesSampleApp/webpack.config.js?range=53)] | ||
|
|
||
| In the following Angular example, the *ClientApp/boot-server.ts* file utilizes the `createServerRenderer` function and `RenderResult` type of the `aspnet-prerendering` npm package to configure server rendering via Node.js. The HTML markup destined for server-side rendering is passed to a `resolve` function call, which is wrapped in a JavaScript `Promise` object of type `RenderResult`. The `Promise` object's significance is that it asynchronously supplies the HTML markup to the page for injection in the DOM's placeholder element. |
There was a problem hiding this comment.
We really like to avoid english versions of code. Would the following work? Do you really need all that type info:
The HTML markup destined for server-side rendering is passed to a resolve function call, which is wrapped in a JavaScript Promise object of type RenderResult.
or even better
The HTML markup destined for server-side rendering is passed to a resolve function call, which is wrapped in a JavaScript Promise object of type RenderResult.
There was a problem hiding this comment.
I prefer the first of your alternatives; the second omits the mention of Promise which is used in the following sentence.
|
|
||
| ## Webpack Dev Middleware | ||
|
|
||
| [Webpack Dev Middleware](https://webpack.github.io/docs/webpack-dev-middleware.html) introduces a streamlined development workflow whereby Webpack builds resources on demand. The middleware automatically compiles and serves client-side resources when a page is reloaded in the browser. The alternate, less efficient approach is to manually invoke Webpack via the project's npm build script when a third-party dependency or the custom code changes. An example of said build script in the `package.json` file is: |
There was a problem hiding this comment.
Files are italic, never code fenced
| * doesn't optimize the client-side code for performance | ||
| 1. **Production**: | ||
| * excludes source maps | ||
| * optimizes the client-side code via bundling & minification |
There was a problem hiding this comment.
Should you link to our B&M article?
|
@scottaddie much better.. Do you have a sample app to point to? |
|
@Rick-Anderson Thank you. There's a link to the sample app in the beginning of the doc. |
|
@scottaddie I think it's ready to ask one of the SPA folks to review it. |
| ms.technology: aspnet | ||
| ms.prod: asp.net-core | ||
| uid: client-side/spa-services | ||
| ms.custom: H1Hack27Feb2017 |
|
|
||
| By [Scott Addie](https://github.com/scottaddie) | ||
|
|
||
| This article describes the value proposition of [SpaServices](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.SpaServices) in building a Single Page Application (SPA) with ASP.NET Core. |
There was a problem hiding this comment.
Could link just to the repo, i.e. https://github.com/aspnet/JavaScriptServices
|
|
||
| <a name="using-spa-services"></a> | ||
|
|
||
| ## Using SpaServices with ASP.NET Core |
There was a problem hiding this comment.
This h2 is practically identical to the h1, and the text under it seems like it's actually the doc intro; it could replace the "this doc covers" text currently located under the h1.
| <a name="what-is-spa-services"></a> | ||
|
|
||
| ## What is SpaServices? | ||
|
|
There was a problem hiding this comment.
Why do we introduce JSServices and then ignore it. I think if it's relevant here some more explanation of the relationship between the two and why JSServices is called a "project" would be helpful.
There was a problem hiding this comment.
Will readers understand what nonopinionated means? Or something like:
Because SpaServices is a nonopinionated, client framework-agnostic library, it doesn't lock you into a particular client framework, library, or coding style.
This almost sounds like a separate paragraph, as it seems off the topic of whether SS can be used to develop SPAs.
|
|
||
| SpaServices provides useful infrastructure such as: | ||
| * [Server-side prerendering](#server-prerendering) | ||
| * [Webpack Dev Middleware](#webpack-dev-middleware) |
There was a problem hiding this comment.
When used in text (as opposed to code or a package name) it might be better to spell out development
|
|
||
| ## Creating a new project | ||
|
|
||
| JavaScriptServices provides pre-configured application templates. SpaServices is used in these templates, in conjunction with different frameworks and libraries such as Angular, Aurelia, Knockout, React, and Vue. |
There was a problem hiding this comment.
We should have a "what is" paragraph for JavaScriptServices somewhere
| | MVC ASP.NET Core with React.js and Redux | reactredux | [C#] | Web/MVC/SPA | | ||
| | MVC ASP.NET Core with Vue.js | vue | [C#] | Web/MVC/SPA | | ||
|
|
||
| To create a new project using one of the SPA templates, include the **Short Name** of the template in the `dotnet new` command. The following command creates an Angular application with ASP.NET Core MVC configured for the server-side: |
| ### Set the runtime configuration mode | ||
|
|
||
| Two primary runtime configuration modes exist: | ||
| 1. **Development**: |
There was a problem hiding this comment.
Does this need to be an ordered list?
|
|
||
| ### Running with Visual Studio 2017 | ||
|
|
||
| Open the *.csproj* file generated by the `dotnet new` command. The required NuGet and npm packages are restored automatically upon project open. This restoration process may take up to a few minutes; and, the application is ready to run when it completes. Click the green run button or press `Ctrl` + `F5`, and the browser opens to the application's landing page. The application runs on localhost according to the [runtime configuration mode](#runtime-config-mode). |
There was a problem hiding this comment.
Ctrl + F5 --> Ctrl+F5 or just Ctrl+F5 (so long as style is consistent throughout the doc; we haven't established a preference for one or the other yet)
| npm test | ||
| ``` | ||
|
|
||
| The script launches the Karma test runner, which reads the settings defined in the *karma.conf.js* file. Amongst other settings, the *karma.conf.js* identifies the test files to be executed via its `files` array: |
|
@Rick-Anderson and @tdykstra I've implemented many of your suggestions. Please take another look. |
|
Fixes #2461 @scottaddie looks great |
|
Maybe you could update the packages to the latest versions typescript, angular, types/node, how can you view the finish doc, I need to login when I click the review URL |
|
@damienbod Unfortunately, the review URL is only available internally. The npm package versions used by the latest stable release of @Rick-Anderson What's the best way for Damien to review this doc without access to the internal review page? |
|
@dend Do we have a timeline on when external customers will be able to display builds? [@]damienbod is asking:
|
|
@bradygaster customer would like to review doc. |
|
I also only reviewed the last commit and approved this one. Would like to take a peek at the document as well if possible :) |
|
Did so, thanks. |
|
ASP.NET Core Tag Helpers provided by SpaServices simplify the implementation of server-side prerendering by invoking the JavaScript functions on the server for you. => ASP.NET Core Tag Helpers provided by SpaServices, simplify the implementation of server-side prerendering by invoking the JavaScript functions on the server. |
|
Some code blocks are JavaScript, but the code is Typescript code. Would it be possible to use Typescript code blocks for the Typescript code? |
Looks like that's a know tag. TypeScript typescript, ts |
|
Additional resources Only Angular is listed. Maybe the other SPA frameworks, libraries could be also listed |
|
@damienbod Nice catches! I've implemented the wording and TypeScript changes. @Rick-Anderson Thoughts on listing other supported SPA frameworks in Additional resources? |
|
nice docs :), looks good. |
|
@Rick-Anderson Is this ready to merge? |
|
@scottaddie is "changes are simply another banned word pushed to the browser" what you meant to commit? Looks like possible Scunthorpe issue... (Sorry if you got 2 notices for this, wasn't sure whether GitHub notifies for comments on merged commits) |
|
@irontoby Thank you for pointing this out! I'll fix it right now. |
Review URL
This is the new SpaServices doc which is intended to serve as a reference rather than an end-to-end tutorial. The goal is to focus on what SpaServices offers to developers creating SPAs with ASP.NET Core. Please review.