From 76c7db42b9cf08928d7d77fa464694d01051059a Mon Sep 17 00:00:00 2001 From: Rick Anderson Date: Mon, 24 Apr 2017 11:19:28 -1000 Subject: [PATCH] Update README.md --- README.md | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 36cddfc..db4ce55 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,11 @@ This project is part of ASP.NET Core. You can find samples, documentation and ge ## What is this? -`JavaScriptServices` is a set of technologies for ASP.NET Core developers. It provides infrastructure that you'll find useful if you use Angular 2 / React / Knockout / etc. on the client, or if you build your client-side resources using Webpack, or otherwise want to execute JavaScript on the server at runtime. +`JavaScriptServices` is a set of client-side technologies for ASP.NET Core. It provides infrastructure that you'll find useful if you: + +- Use Angular 2 / React / Knockout / etc. +- Build your client-side resources using Webpack. +- Execute JavaScript on the server at runtime. This repo contains: @@ -22,22 +26,22 @@ This repo contains: * A Yeoman generator that creates preconfigured app starting points ([guide](http://blog.stevensanderson.com/2016/05/02/angular2-react-knockout-apps-on-aspnet-core/)) * Samples and docs -Everything here is cross-platform, and works with .NET Core 1.0.1 or later on Windows, Linux, or OS X. +It's cross-platform (Windows, Linux, or macOS) and works with .NET Core 1.0.1 or later. ## Creating new applications -If you want to build a brand-new ASP.NET Core app that uses Angular 2 / React / Knockout on the client, consider starting with the `aspnetcore-spa` generator. This lets you choose your client-side framework, and generates a starting point that includes applicable features such as Webpack dev middleware, server-side prerendering, and efficient production builds. It's much easier than configuring everything to work together manually! +If you want to build a brand-new ASP.NET Core app that uses Angular 2 / React / Knockout on the client, consider starting with the `aspnetcore-spa` generator. This lets you choose your client-side framework. It generates a starting point that includes applicable features such as Webpack dev middleware, server-side prerendering, and efficient production builds. It's much easier than configuring everything to work together manually! -To do this, first install Yeoman and these generator templates: +To do this, install Yeoman and these generator templates: npm install -g yo generator-aspnetcore-spa -Then you can generate your new application starting point: +Generate your new application starting point: cd some-empty-directory yo aspnetcore-spa -Finally, once the generator has run and restored all the dependencies, you can start up your new ASP.NET Core Single Page Application: +Once the generator has run and restored all the dependencies, you can start up your new ASP.NET Core SPA: dotnet run @@ -56,7 +60,7 @@ If you have an existing ASP.NET Core application, or if you just want to use the * Find [documentation and usage examples here](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.SpaServices#microsoftaspnetcorespaservices). * `Microsoft.AspNetCore.AngularServices` * This builds on the `SpaServices` package and includes features specific to Angular 2. Currently, this includes validation helpers and a "cache priming" feature, which let you pre-evaluate ajax requests on the server so that client-side code doesn't need to make network calls once it's loaded. - * The code is [here](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.AngularServices), and you'll find a usage example for [the validation helper here](https://github.com/aspnet/JavaScriptServices/blob/dev/samples/angular/MusicStore/wwwroot/ng-app/components/admin/album-edit/album-edit.ts), and for the [cache priming here](https://github.com/aspnet/JavaScriptServices/blob/dev/samples/angular/MusicStore/Views/Home/Index.cshtml#L7-8). Full docs are to be written. + * The code is [here](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.AngularServices), and you'll find a usage example for [the validation helper here](https://github.com/aspnet/JavaScriptServices/blob/dev/samples/angular/MusicStore/wwwroot/ng-app/components/admin/album-edit/album-edit.ts), and for the [cache priming here](https://github.com/aspnet/JavaScriptServices/blob/dev/samples/angular/MusicStore/Views/Home/Index.cshtml#L7-8). Complete documentation is planned. There was previously a `Microsoft.AspNetCore.ReactServices` but this is not currently needed - all applicable functionality is in `Microsoft.AspNetCore.SpaServices`, because it's sufficiently general. We might add a new `Microsoft.AspNetCore.ReactServices` package in the future if new React-specific requirements emerge. @@ -64,15 +68,18 @@ If you want to build a helper library for some other SPA framework, you can do s ## Samples and templates -Inside this repo, [the `templates` directory](https://github.com/aspnet/JavaScriptServices/tree/dev/templates) contains the application starting points that the `aspnetcore-spa` generator emits. If you want, you can clone this repo and run those applications directly. But it's easier to [use the Yeoman tool to run the generator](http://blog.stevensanderson.com/2016/05/02/angular2-react-knockout-apps-on-aspnet-core/). +Inside this repo, [the `templates` directory](https://github.com/aspnet/JavaScriptServices/tree/dev/templates) contains the application starting points that the `aspnetcore-spa` generator emits. You can clone this repo and run those applications directly. But it's easier to [use the Yeoman tool to run the generator](http://blog.stevensanderson.com/2016/05/02/angular2-react-knockout-apps-on-aspnet-core/). -Also in this repo, [the `samples` directory](https://github.com/aspnet/JavaScriptServices/tree/dev/samples) contains examples of using the JavaScript services family of packages with Angular 2 and React, plus examples of standalone `NodeServices` usage for runtime code transpilation and image processing. +The [ `samples` directory](https://github.com/aspnet/JavaScriptServices/tree/dev/samples) contains examples of: + +- Using the JavaScript services family of packages with Angular 2 and React. +- A standalone `NodeServices` usage for runtime code transpilation and image processing. **To run the samples:** * Clone this repo * At the repo's root directory (the one containing `src`, `samples`, etc.), run `dotnet restore` - * Change directory to the sample you want to run (e.g., `cd samples/angular/MusicStore`) + * Change directory to the sample you want to run (for example, `cd samples/angular/MusicStore`) * Restore Node dependencies by running `npm install` * If you're trying to run the Angular 2 "Music Store" sample, then also run `gulp` (which you need to have installed globally). None of the other samples require this. * Run the application (`dotnet run`) @@ -84,8 +91,8 @@ If you're interested in contributing to the various packages, samples, and proje * Cloning the repo * Running `dotnet restore` at the repo root dir - * Going to whatever sample or template you want to run (e.g., `cd templates/Angular2Spa`) + * Going to whatever sample or template you want to run (for example, `cd templates/Angular2Spa`) * Restoring NPM dependencies (run `npm install`) * Launching it (`dotnet run`) -If you're planning to submit a pull request, and if it's more than a trivial fix (e.g., for a typo), it's usually a good idea first to file an issue describing what you're proposing to do and how it will work. Then you can find out if it's likely that such a pull request will be accepted, and how it fits into wider ongoing plans. +If you're planning to submit a pull request, and if it's more than a trivial fix (for example, for a typo), it's usually a good idea first to file an issue describing what you're proposing to do and how it will work. Then you can find out if it's likely that such a pull request will be accepted, and how it fits into wider ongoing plans.