|
1 | | -# JavaScriptServices |
2 | | - |
3 | | -AppVeyor: [](https://ci.appveyor.com/project/aspnetci/javascriptservices/branch/dev) |
4 | | - |
5 | | -This project is part of ASP.NET Core. You can find samples, documentation and getting started instructions for ASP.NET Core at the [Home](https://github.com/aspnet/home) repo. |
6 | | - |
7 | | -## What is this? |
8 | | - |
9 | | -`JavaScriptServices` is a set of client-side technologies for ASP.NET Core. It provides infrastructure that you'll find useful if you: |
10 | | - |
11 | | -- Use Angular / React / Vue / Aurelia / Knockout / etc. |
12 | | -- Build your client-side resources using Webpack. |
13 | | -- Execute JavaScript on the server at runtime. |
14 | | - |
15 | | -Read [Building Single Page Applications on ASP.NET Core with JavaScriptServices](https://blogs.msdn.microsoft.com/webdev/2017/02/14/building-single-page-applications-on-asp-net-core-with-javascriptservices/) for more details. |
16 | | - |
17 | | -This repo contains: |
18 | | - |
19 | | - * A set of NuGet/NPM packages that implement functionality for: |
20 | | - * Invoking arbitrary NPM packages at runtime from .NET code ([docs](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.NodeServices#simple-usage-example)) |
21 | | - * Server-side prerendering of SPA components ([docs](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.SpaServices#server-side-prerendering)) |
22 | | - * Webpack dev middleware ([docs](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.SpaServices#webpack-dev-middleware)) |
23 | | - * Hot module replacement (HMR) ([docs](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.SpaServices#webpack-hot-module-replacement)) |
24 | | - * Server-side and client-side routing integration ([docs](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.SpaServices#routing-helper-mapspafallbackroute)) |
25 | | - * Server-side and client-side validation integration |
26 | | - * "Lazy loading" for Knockout apps |
27 | | - * Samples and docs |
28 | | - |
29 | | -It's cross-platform (Windows, Linux, or macOS) and works with .NET Core 2.0 or later. |
30 | | - |
31 | | -## Creating new applications |
32 | | - |
33 | | -Prerequisites: |
34 | | - |
35 | | -* [.NET Core 2.0](https://www.microsoft.com/net/core) (or later) SDK |
36 | | -* [Node.js](https://nodejs.org/) version 6 (or later) |
37 | | - |
38 | | -With these prerequisites, you can immediately create new ASP.NET Core applications that use Angular, React, or React+Redux without having to install anything extra. |
39 | | - |
40 | | -### Option 1: Creating Angular/React/Redux applications from the command line (cross-platform) |
41 | | - |
42 | | -In an empty directory, run (for example) `dotnet new angular`. Other supported SPA frameworks include React and React+Redux. You can see the list of available SPA templates by running `dotnet new spa`. |
43 | | - |
44 | | -Once the generator has run and restored all the dependencies, you can start up your new ASP.NET Core SPA: |
45 | | - |
46 | | - npm install |
47 | | - dotnet run |
48 | | - |
49 | | -### Option 2: Creating Angular/React/Redux applications using Visual Studio 2017 Update 3 or later (Windows only) |
50 | | - |
51 | | -Using the `File`->`New Project` dialog, select *ASP.NET Core Web Application*. You will then be offered the option to create an application with Angular, React, or React+Redux. When the application is created, you can build and run it in the normal way. |
52 | | - |
53 | | -### More info and other SPA frameworks |
54 | | - |
55 | | -For a more detailed (albeit somewhat outdated) walkthrough, see [getting started with the `aspnetcore-spa` generator](http://blog.stevensanderson.com/2016/05/02/angular2-react-knockout-apps-on-aspnet-core/). |
56 | | - |
57 | | -If you want to build an ASP.NET Core application with Aurelia, Knockout, or Vue, you can use the `Microsoft.AspNetCore.SpaTemplates` package. On the command line, run `dotnet new --install Microsoft.AspNetCore.SpaTemplates`. Then you will be able to run `dotnet new aurelia` (or `dotnet new vue`, etc.) to create your new application. |
58 | | - |
59 | | -## Adding to existing applications |
60 | | - |
61 | | -If you have an existing ASP.NET Core application, or if you just want to use the underlying JavaScriptServices packages directly, you can install these packages using NuGet and NPM: |
62 | | - |
63 | | - * `Microsoft.AspNetCore.NodeServices` |
64 | | - * This provides a fast and robust way for .NET code to run JavaScript on the server inside a Node.js environment. You can use this to consume arbitrary functionality from NPM packages at runtime in your ASP.NET Core app. |
65 | | - * Most applications developers don't need to use this directly, but you can do so if you want to implement your own functionality that involves calling Node.js code from .NET at runtime. |
66 | | - * Find [documentation and usage examples here](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.NodeServices#microsoftaspnetcorenodeservices). |
67 | | - * `Microsoft.AspNetCore.SpaServices` |
68 | | - * This provides infrastructure that's generally useful when building Single Page Applications (SPAs) with technologies such as Angular or React (for example, server-side prerendering and webpack middleware). Internally, it uses the `NodeServices` package to implement its features. |
69 | | - * Find [documentation and usage examples here](https://github.com/aspnet/JavaScriptServices/tree/dev/src/Microsoft.AspNetCore.SpaServices#microsoftaspnetcorespaservices) |
70 | | - |
71 | | -There were previously other packages called `Microsoft.AspNetCore.AngularServices` and `Microsoft.AspNetCore.ReactServices` but these are not currently needed - all applicable functionality is in `Microsoft.AspNetCore.SpaServices`, because it's sufficiently general. |
72 | | - |
73 | | -If you want to build a helper library for some other SPA framework, you can do so by taking a dependency on `Microsoft.AspNetCore.SpaServices` and wrapping its functionality in whatever way is most useful for your SPA framework. |
74 | | - |
75 | | -## Samples |
76 | | - |
77 | | -The [`samples` directory](https://github.com/aspnet/JavaScriptServices/tree/dev/samples) contains examples of: |
78 | | - |
79 | | -- Using the JavaScript services family of packages with Angular and React. |
80 | | -- A standalone `NodeServices` usage for runtime code transpilation and image processing. |
81 | | - |
82 | | -**To run the samples:** |
83 | | - |
84 | | - * Clone this repo |
85 | | - * At the repo's root directory (the one containing `src`, `samples`, etc.), run `dotnet restore` |
86 | | - * Change directory to the sample you want to run (for example, `cd samples/angular/MusicStore`) |
87 | | - * Restore Node dependencies by running `npm install` |
88 | | - * If you're trying to run the Angular "Music Store" sample, then also run `gulp` (which you need to have installed globally). None of the other samples require this. |
89 | | - * Run the application (`dotnet run`) |
90 | | - * Browse to [http://localhost:5000](http://localhost:5000) |
91 | | - |
92 | | -## Contributing |
93 | | - |
94 | | -If you're interested in contributing to the various packages, samples, and project templates in this repo, that's great! |
95 | | - |
96 | | -Before working on a pull request, especially 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. |
| 1 | +This branch exists only to build `Microsoft.AspNetCore.SpaServices.Extensions` for an OOB release. It does not contain sources for any other packages or samples. |
0 commit comments