Microsoft ASP.NET Core JavaScript Services
C# TypeScript JavaScript HTML CSS Shell Other
Permalink
Failed to load latest commit information.
samples Fix react/redux TypeScript build errors caused by breaking changes in… Jan 16, 2017
src Bumping NodeServices/SpaServices versions to 1.1.0-rc1-* for RC1 release Jan 13, 2017
templates Use correct docker base image for csproj projects. Fixes #574. Jan 16, 2017
test Increase Mocha timeout. Trying to fix intermittent test failures on A… Jan 10, 2017
tools Add strong naming and fix DB path on IIS Express Feb 2, 2016
.gitattributes Normalise trailing whitespace and line endings everywhere Mar 1, 2016
.gitignore Update templates for Yarn compatibility Oct 28, 2016
.travis.yml Normalise trailing whitespace and line endings everywhere Mar 1, 2016
CONTRIBUTING.md Create CONTRIBUTING.md Nov 2, 2015
JavaScriptServices.sln fix sln for templates Nov 21, 2016
LICENSE.txt Create LICENSE.txt Nov 2, 2015
NuGet.master.config Normalise trailing whitespace and line endings everywhere Mar 1, 2016
README.md Add AppVeyor status to root README.md Jan 2, 2017
appveyor.yml Instruct AppVeyor to regard the generator-aspnetcore-spa.tar.gz file … Jan 2, 2017
build.cmd Update ASP.NET build scripts May 2, 2016
build.ps1 Switch back to regular KoreBuild now it's updated Oct 24, 2016
build.sh Switch back to regular KoreBuild now it's updated Oct 24, 2016
global.json Specify SDK at repo root Dec 15, 2016
makefile.shade Hopefully fix BuildQuality setting in build Jan 10, 2017
pack-local.sh Split out 'socket' hosting model into a separate optional NuGet packa… Nov 30, 2016

README.md

JavaScriptServices

AppVeyor: AppVeyor

This project is part of ASP.NET Core. You can find samples, documentation and getting started instructions for ASP.NET Core at the Home repo.

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.

This repo contains:

  • A set of NuGet/NPM packages that implement functionality for:
    • Invoking arbitrary NPM packages at runtime from .NET code (docs)
    • Server-side prerendering of SPA components (docs)
    • Webpack dev middleware (docs)
    • Hot module replacement (HMR) (docs)
    • Server-side and client-side routing integration (docs)
    • Server-side and client-side validation integration
    • "Cache priming" for Angular 2 apps
    • "Lazy loading" for Knockout apps
  • A Yeoman generator that creates preconfigured app starting points (guide)
  • Samples and docs

Everything here is cross-platform, and works with .NET Core 1.0.1 or later on Windows, Linux, or OS X.

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!

To do this, first install Yeoman and these generator templates:

npm install -g yo generator-aspnetcore-spa

Then you can 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:

dotnet run 

For a more detailed walkthrough, see getting started with the aspnetcore-spa generator.

Adding to existing applications

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:

  • Microsoft.AspNetCore.NodeServices
    • 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.
    • 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.
    • Find documentation and usage examples here.
  • Microsoft.AspNetCore.SpaServices
    • This provides infrastructure that's generally useful when building Single Page Applications (SPAs) with technologies such as Angular 2 or React (for example, server-side prerendering and webpack middleware). Internally, it uses the NodeServices package to implement its features.
    • Find documentation and usage examples here.
  • 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, and you'll find a usage example for the validation helper here, and for the cache priming here. Full docs are to be written.

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.

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.

Samples and templates

Inside this repo, the templates directory 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.

Also in this repo, the samples directory 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.

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)
  • 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)
  • Browse to http://localhost:5000

Contributing

If you're interested in contributing to the various packages, samples, and project templates in this repo, that's great! You can run the code in this repo just by:

  • 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)
  • 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.