> **This article explores cascading values in Blazor 0.7.0**
>
> **The source code for this article can be found [here](https://github.com/dworthen/BlazorStateManagement/tree/part-03-cascading-parameters)**

**This article is part of a Blazor state management exploration series.**

1. [Blazor State Management Part I - Data-Binding](/posts/blazor-state-management-1-data-binding)
2. [Blazor State Management Part II - Event Delegation](/posts/blazor-state-management-2-event-delegation)
3. Blazor State Management Part III - Cascading Parameters

- - -

[The last article](/posts/blazor-state-management-2-event-delegation) ended with a question. How do we share data within the following component structure?

![Cascading parameters.](/media/event-delegation-complicated.png)

With event delegation, we could update middle components to accept a `person` parameter and pass it through to child components that need it. We would also need to pass event handlers through the middle components. A doable, but a messy and cumbersome process.

Ideally, we would pass parameters from the parent component directly to child components that need them, no matter how nested the child components are. Well, it turns out, we can. [CascadingValue](https://docs.microsoft.com/en-us/aspnet/core/razor-components/components?view=aspnetcore-3.0#cascading-values-and-parameters) is a unique tag that allows us to hoist parameters for child components, even nested ones, to acccess. This should feel familiar to anyone who has used [React context](https://reactjs.org/docs/context.html).

Let's create a `MiddleComponent` to contain the `DisplayPerson` and `UpdatePerson` components.

```dotnet
@* MiddleComponent.cshtml *@
<div class="boxed">
    <h4>DisplayPerson Component</h4>
    <DisplayPerson></DisplayPerson3>
</div>
<div class="boxed">
    <h4>UpdatePerson Componet</h4>
    <UpdatePerson></UpdatePerson3>
</div>
```

Notice that we are no longer passing parameters to `DisplayPerson` or `UpdatePerson`. This is because the components will check the hoisted space for the values instead of receiving them directly as parameters. Update `index.cshtml` to use the newly created `MiddleComponent`.

```dotnet
@* index.cshtml *@
...
<MiddleComponent></MiddleComponent>

@functions {
    protected Person person { get; set; } = new Person { Name = "Derek" };
    ...
}
```

This will not work. Remember, `DisplayPerson` and `UpdatePerson` need a `Person` object to work with. So let's wrap `MiddleComponent` in a `CascadingValue` component to hoist our `person` object.

```dotnet
@* index.cshtml *@
...
<CascadingValue Value="@person">
 	<MiddleComponent></MiddleComponent>
</CascadingValue>
...
```

This is still not enough. `UpdatePerson` also expects a function parameter. A function that will handle updating the state when necessary. Each `CascadingValue` can only hoist one value so we will need to nest tags. 

```dotnet
@* index.cshtml *@
<CascadingValue Value="@person">
    <CascadingValue 
        Value="@HandleChange" 
        Name="HandleChange" 
        T="Action<UIChangeEventArgs>">
        <MiddleComponent></MiddleComponent>
    </CascadingValue>
</CascadingValue>

@functions {
    protected Person person { get; set; } = new Person { Name = "Derek" };
    protected void HandleChange (UIChangeEventArgs e)
    {
        person.Name = e.Value.ToString();
        StateHasChanged();
    }
}
```

The second `CascadingValue` component is hoisting a named parameter. Since the parameter is a method, we need to help Blazor identify the parameter type by specifying the type with the `T` parameter.

Next, we need to update `UpdatePerson` and `DisplayPerson` to use `CascadingParameters` instead of normal parameters. We only need to update the decorators to specify `CascadingParameters`. Nothing else needs to change.

```dotnet
@* UpdatePerson.cshtml *@
...
@functions {
    [CascadingParameter] 
    protected Person person { get; set; }
    [CascadingParameter(Name = "HandleChange")] 
    protected Action<UIChangeEventArgs> CustomOnChange { get; set; }
    ...
}
```

```dotnet
@* DisplayPerson.cshtml *@
...
@functions {
    [CascadingParameter] protected Person person { get; set; }
}
```

Our application should work as it did at the end of the event delegation article. Updating the person's name using the input field should update the name displayed in all components. 

- - -

## Conclusion

Yes, it is possible to use cascading parameters to share state throughout an application, but it is messy. The Blazor docs use CSS style rules or theme information as an example for using cascading parameters. read-only UI state or theme information are good candidates for cascading parameters. Otherwise, not only do the values need to be cascaded but so do the methods that will be responsible for updating the hoisted values. Not to mention, `CascadingValue` can only hoist one value at a time, requiring nested tags for each cascading value.


Cascading parameters provides a way to share data and behavior from ancestor components to child components without having to manually pass parameters down in intermediate components. Components can access the data it needs without requiring parent components to manage data dependencies. In this article, we will explore using cascading parameters, along with event delegation, in order to share data throughout a component tree.

Blazor State Management Part III - Cascading Parameters

> **This article explores event delegation in Blazor 0.7.0**
>
> **The source code for this article can be found [here](https://github.com/dworthen/BlazorStateManagement/tree/part-02-event-delegation)**

**This article is part of a Blazor state management exploration series.**
1. [Blazor State Management Part I - Data-Binding](/posts/blazor-state-management-1-data-binding)
2. Blazor State Management Part II - Event Delegation
3. [Blazor State Management Part III - Cascading Parameters](/posts/blazor-state-management-3-cascading-parameters)

---

[Previously](/posts/blazor-state-management-1-data-binding), we developed a sample application in order to explore data-binding in Blazor. Here is the current component structure of our sample application.

![data-binding component structure](/media/component-structure.png)

The index page shares a `Person` object to two components, `DisplayPerson` and `UpdatePerson`. Changes to `person`  that occur in `UpdatePerson` do not show up in `DisplayPerson`. At least, not automatically. This behavior was observed and discussed in the previous article. 

So how does one share objects across components and ensure that components are working with, and reflecting the most up-to-date state? One way to solve this problem is to use event delegation.

> **Event delegation** refers to the process of using event propagation (bubbling) to handle events at a higher level in the DOM than the element on which the event originated. 
>
> <https://learn.jquery.com/events/event-delegation/>

Instead of handling events in `UpdatePerson`, events are bubbled up to the `index` page. The `index` page will handle the event, make changes to `person` and propagate the changes to child components. `UpdatePerson` and `DisplayPerson` in this case. 

- - -

## Event handler

Add the following `HandleChange` method to the `index.cshtml` page. `HandleChange` will respond to input changes that occur in `UpdatePerson`, updating the `person`'s name and calling `StateHasChanged` to rerender the UI.

```aspnet
@* index.cshtml *@
...
@functions {
...
    private void HandleChange (UIChangeEventArgs e)
    {
        person.Name = e.Value.ToString();
        StateHasChanged();
    }
}
```

- - -

## Event Propagation (Bubbling)

The `HandleChange` event handler is in place. Now, we need to change `UpdatePerson` to bubble onchange events up to `index`/`HandleChange`. We can do this by adding a custom component parameter to `UpdatePerson`.

```aspnet
@* UpdatePerson *@
...
@functions {
    ...
    [Parameter] protected Action<UIChangeEventArgs> CustomOnChange { get; set; }

    private void OnChange(UIChangeEventArgs e)
    {
        CustomOnChange?.Invoke(e);
    }
}
```

The custom parameter, `CustomOnChange`, is defined as an `Action<UIChangeEventArgs>`. Actions are methods that except some list of parameters, `UIChangeEventArgs` in this case, and return nothing (null). Notice that this action defines a method that matches the `HandleChange` method signature. I think you can see where we are going here. 

> **[More in-depth guide to Actions](https://www.codementor.io/aydindev/delegates-func-act-in-c-sharp-du107s5mj)**

The final piece of the puzzle, wiring up the components. Update the `index` page to pass in `HandleChange` to `UpdatePerson`. 

```aspnet
@* index.cshtml *@
...
<UpdatePerson person="@person" 
    CustomOnChange="@HandleChange"></UpdatePerson>
...
```

Essentially, we are exposing the onchange event from `UpdatePerson` to `index` as a custom event, `CustomOnChange`, and handling the event with `HandleChange`. 

Launching this application and updating the name in the input field will show that `DisplayPerson` now updates to reflect the current name. Finally, we have a way to share objects across components.

- - -

## Conclusion

We started with one component structure/relationship and, through this article, and minor tweaks, we ended up with

![event delegation relationship](/media/event-delegation.png)

Event delegation provides a way to organize components in a way that allows for sharing state across components. The process for using event delegation for this purpose is to 1) identify a parent component that will "own" the data and 2) bubble events/changes from child components up to the parent component, the one that "owns" the data, to handle changes. 

There are some drawbacks to this method of sharing state. For example, how do we handle the following case?

![Event delegation with nested components.](/media/event-delegation-complicated.png)

In this case, `DisplayPerson` and `UpdatePerson` still need access to `person` but the middle components know nothing about `person` and don't need to. We could update middle components to accept `person` parameters and pass them through to the child components that need it. We would also need to pass event handlers from the parent component through middle components down to child components. A doable process but messy and cumbersome. We will explore alternative solutions for handling this case in future articles.

Event delegation is only one of many methods for sharing data across components. We will examine other methods in future articles.


Data-binding is a useful concept and tool. In practice, data-binding lets Blazor developers manage and manipulate local component state and rest easy knowing the component UI is always working with, and reflecting the current state. The problem, data-binding does not work with state shared across components. In this article, we explore event delegation. A technique for handling state changes and for sharing state across components. 

Blazor State Management Part II - Event Delegation

> **This article explores data-binding in Blazor 0.7.0**
>
> **The source code for this article can be found [here](https://github.com/dworthen/BlazorStateManagement/tree/part-01-data-binding).**

**This article is part of a Blazor state management exploration series.**

1. Blazor State Management Part I - Data-Binding
2. [Blazor State Management Part II - Event Delegation](/posts/blazor-state-management-2-event-delegation)
3. [Blazor State Management Part III - Cascading Parameters](/posts/blazor-state-management-3-cascading-parameters)

---

MVVM (Model-View-ViewModel) is a UI design pattern that separates the data layer, model, from the presentation layer, view. The pattern bridges the two layers with the ViewModel which is responsible for converting the model into a view-friendly form and for relaying view-driven updates back to the model.

![MVVM Diagram](/media/mvvm-concrete.png)

An important part of the MVVM pattern is the communication between the view and ViewModel. When the ViewModel updates data the view automatically updates to reflect the changes. The opposite is also true. When the view updates data through user interactions, the ViewModel references the most up-to-date data. This is known as data-binding.

In short, data-binding means that the view always reflects the current ViewModel and the ViewModel stays in sync with updates that occur in the view, user-driven or otherwise.

Here is an example of data-binding from the Blazor documentation.

```aspnet
<input type="checkbox" class="form-check-input" id="italicsCheck" bind="@_italicsCheck" />
Current Value: @_italicsCheck

@functions {
	private bool _italicsCheck { get; set; } = false;
}
```

The above is a simple component. The properties defined in the functions section act as our ViewModel and are accessible to the above HTML, the view, through razor syntax. In this case, the view displays a checked checkbox when the ViewModel's `_italicsCheck` is true. Furthermore, the value stored in `_italicsCheck` updates as users toggle the checkbox in the UI to match the new toggled state. This functionality, data-binding, is achieved with the `bind` attribute.

Two-way data-binding out of the box! So Blazor supports the MVVM design pattern, right? Not quite. Let's examine what happens when data is used across components.

```aspnet
@* UpdateMessage.cshtml *@
<div>UpdateMessage Component Current Value: @Message</div>

<div>
    <input type="text" bind="@Message" />
</div>

@functions {
    [Parameter] string Message { get; set; }
}
```

```aspnet
@* DisplayMessage.cshtml *@
<div>Display Message Component Current Value: @Message</div>

@functions {
    [Parameter] string Message { get; set; }
}
```

And update `index.cshtml`

```aspnet
@* index.cshtml *@
@page "/"

<DisplayMessage Message="@Message"></DisplayMessage>
<UpdateMessage Message="@Message"></UpdateMessage>

@functions {
    private string Message { get; set; } = "Hello World";
}
```

Now, two components are using the same data. Let's see what happens when we update the message in UpdateMessage. Do updates propagate to the DisplayMessage component?

![data-binding a string](/media/data-bind-1.png)

Unfortunately, no. Data-binding is limited to the current component and child components. But wait! Like two-way binding on input tags, Blazor supports two-way binding on custom component parameters using the `bind-` prefix attribute. Let's implement that now.

```aspnet
@* index.cshtml *@
...
<DisplayMessage bind-Message="@Message"></DisplayMessage>
<UpdateMessage bind-Message="@Message"></UpdateMessage>
...
```

The `bind-` prefix allows one to bind data to custom-component parameters. Before refreshing the application, we need to add the following `Action` parameter to UpdateMessage and DisplayMessage.

```aspnet
@* DisplayMessage.cshtml and UpdateMessage.cshtml *@
...
@functions {
	...
	[Parameter] Action<string> MessageChanged { get; set; }
}
```

We will examine how this works in a future article. For now, cross your fingers!

![data-binding with bind attribute](/media/data-bind-2.png)

No luck! Surely, the issue is that we are sharing a string across components. Passing a string is to pass by value. So each component is receiving its own copy of the string. AHA! Let's try using a POCO as our state object.

```aspnet
@* Person.cs *@
public class Person
{
    public string Name { get; set; }
}
```

And repeat the same pattern from before...

```aspnet
@* DisplayPerson *@
<div>DisplayPerson Component - Person's Name: @person.Name</div>

@functions {
    [Parameter] Person person { get; set; }
}
```

```aspnet
@* UpdatePerson Component *@
<div>UpdatePerson Component - Person's Name: @person.Name</div>

<div>
    <input type="text" bind="@person.Name" />
</div>

@functions {
    [Parameter] Person person { get; set; }
}
```

Let's not forget to update `index.cshtml` to use the new Person components.

```aspnet
@* index.cshtml *@
...
<DisplayPerson person="@person"></DisplayPerson>
<UpdatePerson person="@person"></UpdatePerson>

@functions {
    ...
    private Person person { get; set; } = new Person { Name = "Derek" };
}
```

Refreshing our browser we get

![Data-binding with poco](/media/data-binding-with-poco.png)

Don't panic! Hope is not lost. Instead of relying on Blazor's data-binding let's try responding to the `onchange` event manually.

```aspnet
@* UpdatePerson.cshtml *@
...
	<input type="text" value="@person.Name" onchange="@OnChange" />
...
@functions {
    ...
    private void OnChange(UIChangeEventArgs e)
    {
        person.Name = (string)e.Value;
    }
}
```

If you refresh the browser, you will see that we still have the same functionality. Well, we didn't break anything. We still have component-scoped data-binding. Why use an event listener instead of bind? Using an event listener allows us to have side effects, such as calling `StateHasChanged`.

```aspnet
@* UpdatePerson.cshtml *@
private void OnChange(UIChangeEventArgs e)
{
    person.Name = (string)e.Value;
    StateHasChanged();
}
```

`StateHasChanged`, if you haven't guessed, is a Blazor function that tells the system that the state has changed which, in turn, triggers a rerender. Blazor renders UI similar to many popular JS frameworks. It maintains a virtual dom. When a rerender occurs, Blazor generates a new virtual dom, diffs it with the previous virtual dom and then minimally updates the real dom.

Maybe, just maybe, manually calling `StateHasChanged` causes Blazor to rerender and diff the entire virtual dom and not just the local component dom. And...

![Data-binding with statehaschanged](/media/data-binding-with-satehaschanged.png)

Turns out, `StateHasChanged` is scoped to the current component and child components. No different from bind.

What gives? DisplayPerson and UpdatePerson receive the same Person object. It is an object! It has to be passed by reference, right? This is true. DisplayPerson and UpdatePerson receive a reference to the same object. The problem lies in how rerendering works in Blazor.

Let's prove that the shortcoming lies within the rendering mechanism. Add the following code to DisplayPerson

```aspnet
...
@functions {
...
    protected async override Task OnInitAsync()
        {
            await base.OnInitAsync();
            System.Timers.Timer timer = new System.Timers.Timer(10000);
            await Task.Delay(6000);
            StateHasChanged();
        }
...
}
```

After 6 seconds, DisplayPerson calls `StatehasChanged`, triggering a rerender. This should give us enough time to load the page, update the state within the UpdatePerson component and wait and see if DisplayPerson will display the updated name after StateHasChanged has been called. Go quick. You have 6 seconds. If all goes well, DisplayPerson, after 6 seconds, should display the updated name since it is referencing the same object.

![Data-binding with a delay](/media/data-binding-with-a-delay.gif)

Notice that the name is updating to match user input

- - -

## Conclusion

In summary, Blazor supports component-based data-binding, a process for keeping the ViewModel and view in sync. Data-binding is component based and will not work across components. In future articles, I will examine methods for sharing data across components and ensuring components use and reflect the most up-to-date data.


Data-Binding. It's the magical glue that binds an application's UI to its business model. Or, more formally, It's a process for updating UI when application state changes and vice versa, keeping the state in sync with changes occurring in the UI. Blazor supports data-binding, but to what extent?

Blazor State Management Part I - Data-Binding


I began programming in TypeScript by accident. I was exploring Microsoft's new ASP.NET Core framework and before I knew it, I was writing code in TypeScript.

It wasn't my fault. My IDE of choice made the decision for me, without my consent. Visual Studio had decided to scaffold out a project with TypeScript. I thought, "why not?". After all, learning TypeScript was a longtime desire of mine and a chore I put off for long enough. It was time to learn TypeScript.

I was immediately drawn to the type system. The compiler provides type safety and valuable feedback. Take the following code for example:

```ts
export function add(a: number, b: number): number {
    return a + b;
}
```

Valid TypeScript. Now let's call, or should I say miscall, `add`.

```ts
add('Hello', { name: "World" });
```

Not so valid. Don't be mistaken, this is valid JavaScript but not valid TypeScript. `'Hello'` and `{ name: "World" }` are invalid arguments for `add` since they are not numbers. The compiler will inform us of this blunder.

Writing application code in TypeScript adds type safety, a great benefit to developers. Editing `add` to accept strings instead of numbers will cause the compiler to explode. That is until we update all calls of `add` to use strings. A valuable feedback loop useful for refactoring. The compiler is the first line of defense.

Writing reusable JavaScript libraries in TypeScript is a different matter. What if we were to package and distribute `add` as a JavaScript library? The following is the compiled JavaScript version of `add`.

```js
export function add(a, b) {
    return a + b;
}
```

That's right. TypeScript's compiler removes all information about types. This makes sense. TypeScript compiles to valid JavaScript, which does not have a static type system. Though it provides compile-time type safety, TypeScript **does not** provide runtime type safety.

Compilation removes type information and restraints on `add`. Developers using the compiled library may call `add` with strings instead of numbers. Nothing prevents them from doing so.

---

## Solution

As always with library development, consider end users and write unit tests for all use cases. On top of unit tests, consider writing runtime type checks. This will prevent misuse of code or provide relevant feedback when misuse occurs.

```ts
export function add(a: number, b: number): number {
    if(typeof a !== 'number') {
        throw new TypeError('....');
    }
    if(typeof b !== 'number') {
        throw new TypeError('....');
    }
    return a + b;
}
```

The above is still valid, and beautiful, TypeScript. The compiler has no problems with the extra type guards.


Intellisense, type definitions, tooling, and documentation. A few of the benefits that follow from TypeScript's compile-time static type system but it's not all good news. There are some drawbacks. For starters, the type checking, and thus type safety, occur at compile time. What about Runtime type safety?

TypeScript and Runtime Type Safety


## Problem

You've written a TypeScript library. Now what? Time to publish, of course. But how? Do you publish it as a TypeScript module or compile it to JavaScript? Should it run in browser or Node.js? Or both? What about ES5 versus ES6 or ESNext? And don't forget, some people prefer AMD modules.

In this article, I address all of these concerns and more. I will show you how to publish a TypeScript library to a broad audience. Publishing a TypeScript library can be complicated, but it doesn't have to be.

## TLDR

Use tsc to compile TypeScript source code to ES modules. Use webpack + babel to transpile ES modules to a umd package. Providing ES modules and a umd package supports a larger developer community.

---

## Solution

A two-step build process.

1. Compile TypeScript source code to ES modules using `tsc`, the TypeScript compiler.
2. Bundle ES modules into a single umd module using webpack and babel.

---

## Why

Providing both ES modules and a umd package gives developers options. Those working in modern ES2015+ environments can use the ES modules while the umd package supports those working in commonjs or web browser environments. Plus, modern build tools, such as Webpack and rollup, take advantage of ES modules. Build tools will parse, traverse and eliminate unused (dead) code of ES module dependencies.

---

## Why Webpack

Unfortunately, the [TypeScript compiler does not support global fallbacks when compiling to umd](https://github.com/Microsoft/TypeScript/issues/8436). In short, umd packages produced by TypeScript do not support web browsers. Webpack, on the other hand, builds umd packages that support web browsers along with commonjs and amd environments.

---

## Why Babel

To transpile ES2015 to the more widely supported ES5.

---

## Is Compilation Necessary

What about writing TypeScript libraries for TypeScript developers? Is a build process necessary?

Yes. TypeScript does not compile dependencies (packages listed in node_modules). TypeScript libraries need to be compiled to JavaScript before publishing, even if the intended audience is TypeScript developers.

---

## Project Structure

```asciidoc
Project/
|-- src/
    |-- sayHello.ts
    |-- index.ts
|-- tsconfig.json
|-- webpack.config.js
|-- package.json
```

### sayHello.ts

A simple function to say hello! This is the only functionality of my awesome library.

```js
export function sayHello(name: string): void {
  console.log(`Hello, ${name}`);
}
```

### index.ts

This is the main entry point to the library and, as such, exposes the public API.

```js
export { sayHello } from "./sayHello";
```

### tsconfig.json

The following options instruct the TypeScript compiler to output ES2015 modules.

```json
{
  "compilerOptions": {
    /* Basic Options */
    "target": "ES2015" /* Build to ES2015 */,
    "module": "ES2015" /* using ES2015 modules */,
    "lib": ["es2015", "dom"] /* Using ES2015 features and DOM APIs  */,
    "declaration": true /* Generates corresponding'.d.ts' files. */,
    "declarationDir": "./dist/typings/" /* build '.d.ts' files to ./dist/typeings */,
    "outDir": "./dist/esm/" /* build to ./dist/esm/ */
  },
  "files": ["./src/index.ts"],
  "include": ["./src/**/*.ts"]
}
```

- **declarations**: set to true, `tsc` outputs type definition files which, in turn, provides code intellisense support to TypeScript developers using the library.
- **files** specifies which files to compile. In this case, the main entry point to the library is listed. Compiling the main entry point, index.ts, compiles the rest of the library through dependencies.

### webpack.config.js

Webpack bundles ES modules outputted by `tsc` as a single umd package, targeting ES5. Developers can load the umd package within web browsers, via a script tag, or within commonjs or amd environments.

```js
const path = require("path");

module.exports = (env, argv) => {
  return {
    entry: {
      index: path.resolve(__dirname, "./dist/esm/index.js")
    },
    output: {
      path: path.resolve(__dirname, "./dist/umd"), // builds to ./dist/umd/
      filename: "[name].js", // index.js
      library: "myLibrary", // aka window.myLibrary
      libraryTarget: "umd", // supports commonjs, amd and web browsers
      globalObject: "this"
    },
    module: {
      rules: [{ test: /\.t|js$/, use: "babel-loader" }]
    }
  };
};
```

- **entry** specifies the entry point to the library. In this setup, webpack transpiles ES2015 to ES5 and does not compile TypeScript source code. For this reason, the file outputted by `tsc`, which is an ES2015 module, is specified as the input for webpack.
- **library** specifies the global variable name to use within web browsers.
- **globalObject** sets the global fallback object. The default is `window`, which is not defined in commonjs environments. Setting the global fallback object to `this` generates a umd package that supports both commonjs and web browser environments.
- **module.rules**: In this setup, webpack uses babel to transpile ES2015 code to the more widely supported ES5 syntax.

### package.json

Add the following to package.json

```json
{
  "main": "./dist/umd/index.js",
  "module": "./dist/esm/index.js",
  "types": "./dist/typings/index.d.ts",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "build": "webpack",
    "prebuild": "tsc"
  },
  "devDependencies": {
    "babel-core": "^6.26.0",
    "babel-loader": "^7.1.4",
    "typescript": "^2.7.2",
    "webpack": "^4.1.1",
    "webpack-cli": "^2.0.11"
  }
}
```

- **main** specifies the location of the umd package. Commonjs environments use this as the main entry point to the library.
- **module** specifies the location of the main ES2015 module. Consuming packages that use webpack or rollup will use this as the main entry point to the library and will eliminate unused (dead) code when bundling the library.
- **types** specifies the location of type definition files. Type definition files provide code intellisense and autocompletion support to TypeScript developers using the library.
- **scripts.build** runs `webpack`, transpiling ES2015 modules to an ES5 umd package.
- **scripts.prebuild** runs `tsc`, compiling TypeScript to ES2015 modules. This command automatically runs prior to `npm run build`.
- **devDependencies** lists the minimal set of packages needed to build both ES2015 modules and a umd package. Don't forget to run `npm install`.

---

## Build

```shell
$ npm run build
```

Outputs

![npm-build](/media/npm-build.png)

---

## Consume the built code

### Web Browsers via script tags

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <script src="./path/to/dist/umd/index.js"></script>
    <script>
      // webpack exposes the library as a global, myLibrary
      myLibrary.sayHello("World");
    </script>
  </head>
  <body></body>
</html>
```

### commonjs (Node)

```js
var myLibrary = require("myLibrary");

myLibrary.sayHello("World");
```

### ES modules

```js
import { sayHello } from "myLibrary/esm/sayHello";

sayHello("World");
```

Developers using webpack do not have to specify ES module paths. Webpack will automatically use the ES modules based on the module path specified in package.json.

**webpack**

```js
import { sayHello } from "myLibrary";

sayHello("World");
```


You've written a TypeScript library. Now what? Time to publish, of course. But how? Do you publish it as a TypeScript module or compile it to JavaScript? Should it run in browser or Node.js, or both? What about ES5  versus ES6 or ESNext? And don't forget, some people prefer AMD modules.

Authoring TypeScript Libraries


[ASP.NET Core](https://www.microsoft.com/net/learn/apps/web); When the cross-platform version of the infamous ASP.NET we all love (to hate?) was released I immediately began exploring the process of deploying a .NET web application to a Linux host. After all, I was already running several [Node.js](https://nodejs.org) web applications on a Linux box so why not add a few ASP.NET applications and host all apps under one roof. Plus I had to see it to believe it; a Microsoft web app running in a Linux environment!

In this article, I walk through the process of deploying an ASP.NET application to a Linux environment. The application will run inside a [Docker](https://www.docker.com/) container within a Ubuntu host. The Docker environment is managed with [Dokku](http://dokku.viewdocs.io/dokku/) which makes it possible to kick off builds and deployments with simple git pushes. Dokku will also handle (sub)domain routing by managing [nginx](https://www.nginx.com/); good riddance.

**Update:** The final source code lives [here](https://github.com/dworthen/aspnet-linux-edition/tree/1.0.0).

---

## Setup

1. [Download and install dotnet](https://dot.net) on your development environment.
2. [Install Dokku on a fresh Ubuntu environment](http://dokku.viewdocs.io/dokku/getting-started/installation/).
   - I am using [Linode](https://www.linode.com/) to host a Ubuntu 16.04 LTS environment. Instructions for installing Dokku on Linode can be found [here](http://dokku.viewdocs.io/dokku~v0.6.2/getting-started/install/linode/).
   - Alternatively, use [Windows Subsystem for Linux](https://msdn.microsoft.com/en-us/commandline/wsl/install-win10) to explore this process on a local machine.
3. [Optional] Point a [FQDN](https://en.wikipedia.org/wiki/Fully_qualified_domain_name) towards the Ubuntu host. If using Linode, as I am, then check out their [DNS Manager](https://www.linode.com/docs/networking/dns/dns-manager-overview).
   - For this article, I have both derekworthen.com, `<SERVER_ADDRESS>`, and blog-demo-aspnet-linux-environment.derekworthen.com, `<FQDN>`, pointing towards my Dokku configured server. `<APP_NAME>` refers to blog-demo-aspnet-linux-environment.

---

## App Creation

Since this article is focused on the process of deploying to a Ubuntu host we will stick with creating a bare-bones web application. Visit Microsoft docs for an in-depth guide to [getting started with ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/mvc/razor-pages/?tabs=visual-studio).

#### .NET Core CLI

At the time of this writing, I am using .Net CLI tools and SDK version 2.0.2 to create a sample app but any version of .NET Core should work.

**Note:** Run `dotnet --info` to print out the version of dotnet CLI tools and SDK installed.

```shell
mkdir <APP_NAME> && cd <APP_NAME> && dotnet new razor
```

Verify the app builds and runs with `dotnet restore && dotnet run`. Head over to localhost:5000 for a front row viewing of the out-of-the-box ASP.NET template in all its glory.

![Default ASP.NET application running on port 5000](/media/aspnetcore-app.png)

---

## App Management with Dokku

Shell into the Ubuntu host as the dokku user account created during the setup process. I am using the [Windows Subsystem for Linux](https://msdn.microsoft.com/en-us/commandline/wsl/install-win10) to drop into Bash and connect to the server instead of using an application like [Putty](http://www.putty.org/). Mac and Linux users can ignore the `bash -c` part of the command and delete the quotes surrounding the `ssh` command.

```shell
bash -c "ssh dokku@<SERVER_ADDRESS>"
```

#### Dokku

```shell
# Linux host
$ dokku apps:create <APP_NAME>
```

This will create a git repo at `<SERVER_ADDRESS>:<APP_NAME>`, e.g., derekworthen\.com:blog-demo-aspnet-linux-environment in my case. Dokku will also register a reverse proxy routing with nginx using the `<APP_NAME>` as the subdomain to create the app's `<FQDN>`, e.g., blog-demo-aspnet-linux-environment.derekworthen.com. By default, Dokku will configure nginix to route all traffic on port 80 and 443 (if SSL is enabled) that matches the `<FQDN>` to port 5000 of the app's docker container.

#### Git

On the local machine, initialize git and add a remote location for the newly created dokku repo. (Don't forget to add an [appropriate](https://www.gitignore.io/api/aspnetcore) [.gitignore](https://www.gitignore.io/) file to the project.)

```shell
# Local development machine
git init && git add . && git commit -m "initial commit"
# Must use the dokku user account created during the setup process
git remote add dokku dokku@<SERVER_ADDRESS>:<APP_NAME>
```

Up until now, we have been following the [basic guide for deploying a Dokku app](http://dokku.viewdocs.io/dokku/deployment/application-deployment/). We will now follow the instructions for [Dockerfile deployment](http://dokku.viewdocs.io/dokku/deployment/methods/dockerfiles/). Dokku will build, run and deploy a docker container based on the provided Dockerfile.

#### Dockerfile; Building and Running ASP.NET Core Applications

Create a `Dockerfile` in the root of the application with the following contents.

```docker
# Stage 1. Building.
# May need use a different tag to get the build to work.
# https://hub.docker.com/r/microsoft/aspnetcore-build/
FROM microsoft/aspnetcore-build:2.0.2
WORKDIR /source

# caches restore result by copying csproj file separately
# copies project files into the /source/ of the container.
COPY *.csproj .

# Restore dotnet dependencies
RUN dotnet restore

# copies the rest of your code into /source/
COPY . .

# microsoft/aspnetcore-build image contains Node
# so may also run npm install
# or other npm related scripts.
# RUN npm install
# RUN npm run build

# Builds to /out in the root of the container
RUN dotnet publish --output /out/ --configuration Release

# Set environment variables for container
# Dokku maps external port 80 to internal port 5000 and
# the following lines tells ASP.NET to listen on port 5000
# May also omit the following line and add EXPOSE 80
# This will tell dokku to setup port mapping 80:80 instead 80:5000
# and omitting this environment variable will also tell ASP.NET Core
# to listen on port 80
ENV ASPNETCORE_URLS http://*:5000
# EXPOSE 80

# Stage 2. Running the application
WORKDIR /out
ENTRYPOINT ["dotnet", "<APP_NAME>.dll"]
```

The above Dockerfile provides a runtime environment along with tools to build from source code. In a future article, I will cover deploying to a Dokku configured server using a CI/CD pipeline where the build artifacts are created prior to the Docker image. In such scenario, the Docker container does not need build tools and can be imaged from `microsoft/aspnetcore` for the runtime environment.

#### Deploy

It is finally time to push the project to the hosting server with git and watch Dokku build and run the application!

```shell
git add Dockerfile && git commit -m "Add Dockerfile"
git push dokku master
```

If all goes well, Dokku will build and deploy a docker container housing our beautiful ASP.NET application and expose it to the world at the configured `<FQDN>`, e.g., http://blog-demo-aspnet-linux-environment.derekworthen.com/.

![Deploying a Dokku app](/media/deploy-dokku-app.png)

## Conclusion

Using Dokku as a simple [PaaS](https://en.wikipedia.org/wiki/Platform_as_a_service), we managed to deploy an ASP.NET Core web application to a Ubuntu server bundled as a Docker container. Now that the app creation and configuration is out of the way, changes pushed to the dokku remote location will rebuild and redeploy the application.

---

## Bonus; SSL Encryption

With the [Lets Encrypt](https://letsencrypt.org/) [Dokku plugin](https://github.com/dokku/dokku-letsencrypt), this could not be easier.

#### Install

```shell
# Need to be logged in as a sudo user instead of the dokku user account
$ sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git
```

#### Configure

```shell
$ dokku config:set --no-restart <APP_NAME> DOKKU_LETSENCRYPT_EMAIL=<EMAIL>
```

#### Enable

```shell
$ dokku letsencrypt <APP_NAME>
```

#### Auto-renew

```shell
$ dokku letsencrypt:cron-job --add
```

#### Verify

```shell
$ dokku proxy:report <APP_NAME>
```

Look for a https:443:5000 port mapping in the output.

#### Test

Open your favorite web browser and navigate to the https (or http as it should redirect to https) version of your site.


ASP.NET Core + Linux = Freedom. Love ASP.NET? What about Linux? Do you wish to bring the two together? Well now you can with ASP.NET core. Deploy your favorite web stack to your favorate hosting environment. Or, develop from the comfort of your favorite MacBook or Linux box.

ASP.NET Core. Linux Edition


Scrolling down a long list of tabular data without fixed column headings is annoying.

## TLDR

[Skip to the end to view source code and working demo](#demo)

---

Most solutions solutions to the question "how to create [sticky table headers](https://css-tricks.com/scroll-fix-content/)" typically take one of two approaches.

1. Add a fixed position to the thead or first row of the table. This approach is simple and suffices if the table is the first or only element on the page. What I am after is a scroll-then-fixed solution. Here is an [example](https://css-tricks.com/examples/PersistantHeaders/) of what I am after.
2. Use JavaScript to duplicate the first table row and place it in a new table fixed to the top of the page and reveal or hide the duplicated row depending on the viewer's scroll position. This approach feels messy and and its worth mentioning that any event listeners set on the original elements will not work on the duplicated row (unless using [event delegation](https://davidwalsh.name/event-delegate)).

The approach I am after is somewhere in the middle. A scroll-then-fixed solution using the original column headings to maintain event listeners.

#### HTML

```html
<table>
  <thead>
    <tr>
      <th>Col 1</th>
      <th>Col 2</th>
      <th>Col 3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>One</td>
      <td>Two</td>
      <td>Three</td>
    </tr>
    ...
  </tbody>
</table>
```

The HTML is straightforward. Moving on...

#### CSS

```css
.fixed {
  position: fixed;
  top: 0;
}
```

Not much to the CSS either. The `.fixed` class will be added to the thead element when a viewer scrolls to the table.

#### JS

```js
/**
* First Calculate
*   - Where the thead lies on the page
*   - Where the table lies on the page
*   - Table height
**/
var table = document.querySelector('table'),
    thead = table.querySelector('thead'),
    theadOffset = thead.getBoundingClientRect().top,
    tableHeight = +getComputedStyle(table)
                   .getPropertyValue('height')
                   .split('px')[0],
    tableOffset = table.getBoundingClientRect().top,
    tableCells = document.querySelectorAll('th, td');

// Set the widths on all table cells so they dont resize when fixing
// the first row
for (var i = 0, l = tableCells.length; i < l; i++) {
  var cell = tableCells[i];
  cell.width = getComputedStyle(el).getPropertyValue('width');
}

function fixTableHeader(e) {
  // If viewer has scrolled past the first row
  // then fix/stick it to the top of the page
  if( window.pageYOffset > theadOffset ) {
    thead.classList.add('fixed');
  }

  // If viewer has scrolled back above or past the table
  // then unfreeze the first row.
  if ( window.pageYOffset < theadOffset ||
       window.pageYOffset > (tableOffset + tableHeight)) {
      thead.classList.remove('fixed');
  }

}

// Listen...
window.addEventListener('scroll', fixTableHeader, false);
```

## DEMO

<p data-height="265" data-theme-id="dark" data-slug-hash="XKKMBo" data-default-tab="result" data-user="dworthen" data-embed-version="2" data-pen-title="Fixed Table Head" data-preview="true" class="codepen">See the Pen <a href="https://codepen.io/dworthen/pen/XKKMBo/">Fixed Table Head</a> by Derek Worthen (<a href="https://codepen.io/dworthen">@dworthen</a>) on <a href="https://codepen.io">CodePen</a>.</p>
<script async src="https://production-assets.codepen.io/assets/embed/ei.js"></script>


Large HTML tables got you down? Easily fix table headers for readability. Best part. No framework or library necessary.

Fixed HTML Table Header


Hello world! What else is there to say?

This is my bajillionth attempt at starting a blog. Each attempt has resulted in the same outcome; loss of interest and destruction of once beloved blog.

Let's see if this one sticks around.
