Forem: TJ VanToll

Establishing a Robust MLOps Workflow for TinyML

TJ VanToll — Tue, 26 Sep 2023 17:37:10 +0000

A machine learning model is only as good as the data it’s trained on. Gathering a robust set of training data is challenging for any ML project, but it’s especially difficult in the world of TinyML, where devices are often underpowered and running in areas with limited connectivity.

Here at Blues we specializing in making connectivity easy for embedded projects, and together with our friends at Edge Impulse and Zephyr, we’ve put together a workflow that we think helps make MLOps—or the process of continuously improving an ML model—possible for tiny devices.

In this article I’m going to lay out an opinionated way to implement a robust MLOps process. We’ll start by looking at how to collect ML data from your remote devices, and then show how you can update ML models running on our devices in the field. At the end you’ll have a workflow that looks like this.

Let’s get started.

NOTE: See Optimized MLOps with Edge Impulse, Blues, and Zephyr on YouTube for a video version of this tutorial.

Collecting ML Data

For this article we’re going to assume we manage a fleet of devices tasked with monitoring industrial equipment. Each device is fitted with an accelerometer that measures machine vibrations, and runs those readings through an ML model that has been trained to detect abnormalities.

To adopt an MLOps workflow, this project needs a way to gather accelerometer samples from the field, and a way to send those samples to the cloud so that they can be used to train an updated model.

To send the data we’re going to use the Blues Notecard.

The Notecard is a system on module that makes connectivity simple for embedded projects. Specifically, the Notecard offers:

500MB of cellular connectivity
Global cellular over LTE-M, NB-IoT, or Cat-1
Secure “off the internet” communications from device-to-cloud
Low-power hardware (~8µA when idle), and power-conscious firmware
Easy embedding with onboard M.2 Key E connector or via a companion board

The Notecard is great for connectivity on remote devices as it can work in areas without Wi-Fi coverage, and can work on equipment that moves between locations or on vehicles. You can even use the Notecard for asset tracking.

To communicate with the Notecard in our project we need a few other pieces of hardware.

Setting up your hardware

The easiest way to get started with the Notecard is with a Blues Starter Kit. The Starter Kit comes with a development board (Notecarrier), as well as a Swan microcontroller that can run this project’s firmware.

NOTE: The Blues quickstart has full details on how to assemble a Blues Starter Kit.

With the Starter Kit assembled, the last thing we need is an accelerometer to use to take readings. For that accelerometer we’ll use an LIS3DH, which you can connect to the Starter Kit’s Notecarrier via a Qwiic cable.

With all hardware assembled, let’s look at the firmware we’ll use to gather the accelerometer readings.

The Firmware

This project’s firmware is responsible for gathering readings from the accelerometer, and using the Notecard to send those readings to the cloud.

For the firmware implementation we’re using Zephyr, as Zephyr is low-level enough to give us access to features like threading, while high-level enough to provide sensor APIs and other development conveniences. Plus, Zephyr firmware runs great on the STM32-based boards like the Swan, and the Notecard has a ready-to-use Zephyr SDK.

The full firmware source code for this project is available on GitHub, and I will highlight some of the most important parts here.

First, the firmware has to establish a connection between the Notecard and the Notecard’s backing cloud service, Notehub. It does so by performing a hub.set request on the Notecard, and sending a ProductUID that tells what project to associate this Notecard with.

J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "product", "com.your-company:your-product-name");
JAddStringToObject(req, "mode", "continuous");
JAddStringToObject(req, "sn", "your-device-name");
NoteRequest(req);

A couple of notes on the code above:

All of the Notecard’s API use JSON. The Notecard’s C SDK includes a number of helper functions such as JAddStringToObject to make it easier to create JSON objects and send them to the Notecard.
The development board that comes in a Blues Starter Kit, the Notecarrier F, performs all the necessary wiring so that the Swan can communicate with the Notecard via I2C. The NoteRequest API performs this communication.

With a connection with Notehub established we next need to gather data from the accelerometer. The Zephyr code to take a reading from the LIS3DH is relatively straightforward on its own.

struct sensor_value accelerometerData[3];
int rc = sensor_sample_fetch(sensor);
if (rc != 0) {
    printk("Failed to fetch sensor data (error: %d)\n", rc);
    continue;
}

rc = sensor_channel_get(sensor, SENSOR_CHAN_ACCEL_XYZ, accelerometerData);
if (rc != 0) {
    printk("Failed to get sensor data (error: %d)\n", rc);
    continue;
}

float x = sensor_value_to_float(&accelerometerData[0]);
float y = sensor_value_to_float(&accelerometerData[1]);
float z = sensor_value_to_float(&accelerometerData[2]);
printk("Reading - x: %f, y: %f, z: %f\n", x, y, z);

This code snippet takes a single accelerometer reading and places the values in three floating point variables named x, y, and z.

For this example we need code that is a little more complex though, as we’re not taking one accelerometer reading—instead, we’re taking a series of readings over a period of time so that it can be sent to an ML model to look for patterns.

For this project we’re using Edge Impulse to create and train our models. After you’ve built a model with Edge Impulse, Edge Impulse lets you download an SDK with sample code that helps you gather sensor data at the intervals their platform expects for training purposes. Here’s what that ends up looking like in our Zephyr code.

struct sensor_value accelerometerData[3];
float *buffer = (float *)malloc(EI_CLASSIFIER_DSP_INPUT_FRAME_SIZE * sizeof(float));

for (size_t ix = 0; ix < (EI_CLASSIFIER_DSP_INPUT_FRAME_SIZE - 2);
    ix += EI_CLASSIFIER_RAW_SAMPLES_PER_FRAME)
{
    // Determine the next tick (and then sleep later)
    uint32_t next_tick_ms = NoteGetMs() + EI_CLASSIFIER_INTERVAL_MS;

    int rc = sensor_sample_fetch(sensor);
    if (rc != 0) {
        printk("Failed to fetch sensor data (error: %d)\n", rc);
        continue;
    }

    rc = sensor_channel_get(sensor, SENSOR_CHAN_ACCEL_XYZ, accelerometerData);
    if (rc != 0) {
        printk("Failed to get sensor data (error: %d)\n", rc);
        continue;
    }

    float x = sensor_value_to_float(&accelerometerData[0]);
    float y = sensor_value_to_float(&accelerometerData[1]);
    float z = sensor_value_to_float(&accelerometerData[2]);
    printk("x: %f, y: %f, z: %f\n", x, y, z);

    buffer[ix] = x;
    buffer[ix + 1] = y;
    buffer[ix + 2] = z;

    int32_t delay_ms = next_tick_ms - NoteGetMs();
    NoteDelayMs(delay_ms < 2 ? delay_ms : 2);
}

The various constants in this sample, EI_CLASSIFIER_DSP_INPUT_FRAME_SIZE, EI_CLASSIFIER_RAW_SAMPLES_PER_FRAME, and EI_CLASSIFIER_INTERVAL_MS, help dictate exactly how often the code takes accelerometer samples and loads them into the buffer. If you run the code and look at the logs you’ll see the accelerometer samples logged live.

With the data loaded into a buffer variable, our firmware’s last task is to send that data to Notehub.

Sending the Data

Large accelerometer samples like we’re using in this project require a decent amount of storage, and historically, working with these larger data packets was problematic for the Notecard, as the Notecard is primarily a low-bandwidth and low-power friendly device.

However, the new Notecard v5.3.1 firmware release includes a new feature aimed at drastically speeding up data transfer for these types of transfers, and allowing you to upload up to 128kb at a time—which is plenty for our situation.

The new Notecard APIs are named card.binary, and the way you use them in Zephyr apps is with the NoteBinaryStoreTransmit and NoteBinaryStoreReceive methods. Here’s what that looks like in our sample.

NoteBinaryStoreTransmit((uint8_t *)buffer,
    (EI_CLASSIFIER_DSP_INPUT_FRAME_SIZE * sizeof(float)),
    (EI_CLASSIFIER_DSP_INPUT_FRAME_SIZE_COBS * sizeof(float)),
    0);

The NoteBinaryStoreTransmit method loads the buffer into a dedicated area of the Notecard’s memory. Once loaded, you can send the data to your Notecard using the Notecard’s web.post method with the binary flag set to true. Here’s what that looks like.

J *req = NoteNewRequest("web.post");
JAddStringToObject(req, "route", "ingest");
JAddStringToObject(req, "content", "binary/octet-stream");
JAddBoolToObject(req, "binary", true);
NoteRequest(req);

At this point our code is now sending batches of accelerometer readings to Notehub as a binary stream of floating-point values. Our final task is to write an endpoint that can accept that stream, parse out the floating-point values, and send them to Edge Impulse as new training data for our ML model.

Getting the Data to Edge Impulse

In this step we’re going to look at how to create an HTTP server that can accept data from Notehub and forward it to Edge Impulse. The example code I’m providing is written in Node.js, Express, and JavaScript, as that’s my toolchain of choice, but the server needed for this step can be written in any language and using any framework you’d like.

As with before, the full source code required to create the server is open source and available on GitHub, and I’ll be highlighting the most important parts here.

At the highest level, this endpoint has to listen for POST requests coming in at the root of the server. Here’s how that’s done in Express.

const express = require("express");
const app = express();

app.post("/", async (req, res) => {
  ...
});

Once you have the request, you next have to parse out the floating-point accelerometer values coming from Notehub. Specifically, the code has to parse the request, get out 32-bit floating point values one at a time, and put them into an array of readings to use later. Here’s what that code looks like in JavaScript.

const binaryFromRequest = Buffer.from(request, "binary");
const dataView = new DataView(binaryFromRequest.buffer);

for (let i = 0; i <= buffer.length - 1; i += 12) {
  let x = dataView.getFloat32(i, true);
  let y = dataView.getFloat32(i + 4, true);
  let z = dataView.getFloat32(i + 8, true);
  data.push([x, y, z]);
}

With the data aggregated, the last step is to get our data to Edge Impulse. For this, Edge Impulse provides an ingestion API that expects data in a given format, and places a new entry in your model’s training set.

Here’s what the code to do that in JavaScript looks like.

const emptySignature = Array(64).fill("0").join("");
const body = {
    protected: {
        ver: "v1",
        alg: "none",
        iat: Math.floor(Date.now() / 1000),
    },
    signature: emptySignature,
    payload: {
        device_name: "device-1",
        device_type: "LIS2HH12",
        interval_ms: 1,
        sensors: [
            { name: "accX", units: "m/s2" },
            { name: "accY", units: "m/s2" },
            { name: "accZ", units: "m/s2" },
        ],
        values: data,
    },
};

try {
    await fetch("https://ingestion.edgeimpulse.com/api/training/data", {
        method: "POST",
        headers: {
            "x-api-key": process.env.EDGE_IMPULSE_API_KEY,
            "x-file-name": "test",
            "x-label": "idle",
            "Content-Type": "application/json",
        },
        body: JSON.stringify(body),
    });
} catch (e) {
    console.log("Error publishing data", e);
}

Now that you have a server you need to make the server available on the public internet. You can do this via your favorite hosting provider, or, if you’re looking for a quick way to test you can use a service like localtunnel or ngrok.

I’m a big fan of ngrok as I’ve found it works well and they have a generous free tier. After installing, you can run ngrok with a simple command from your terminal or command prompt.

ngrok http 3000

Running this command makes the provided port (in this case 3000) available on the public internet at the provided URL.

Once you have this URL your very last step is to create a proxy route in Notehub. The proxy route provides the connection so that Notehub knows to invoke your web server when it receives a web.post request from the Notecard. Here’s an example of the proxy route you need to create, making sure to provide your own URL for the URL field.

And with that—you’re all set. If you start up your firmware on your device it’ll start collecting accelerometer samples. The firmware will then use the Notecard to send your data to Notehub, which invokes your proxy route, which sends the data to Edge Impulse where you can further refine your ML models.

Pretty cool!

The power of this approach is that it can run in any environment that has cellular connectivity. Meaning, you could adapt this code to run on your production hardware, and start collecting training data from devices in real-world conditions.

Exactly how you’ll want to use this code will likely vary. Maybe you’d want to take a few samples a day at different intervals. Maybe you’ll want to create a Notehub environment variable and only send readings when that variable is activated. The idea behind this sample is to you how the raw data transfer works, and to serve as inspiration for the code and techniques you may want to incorporate into your own projects.

And speaking of techniques you may want to incorporate, I have one more fun thing to show you.

Updating ML Models

In this article we’re looking at how to implement a robust MLOps process. In the previous section we saw how to gather training data from devices in the field, which allows you to continuously improve your ML models with real data. But that leaves a big problem—after you’ve done the work to build an improved version of your model, how do you get that model back out to your devices in the field?

The Notecard offers a compelling answer to this question with Notecard Outboard Firmware Update.

What is Notecard Outboard Firmware Update?

Over-the-the firmware updates are table stakes in IoT, but implementing the updates themselves is often a complex and highly risky endeavor. Most firmware-update processes require developers to write code, generally placed within the application itself, or within its RTOS, requiring a special ‘bootloader’ and firmware layout. This requires a high degree of skill, is susceptible to bad updates “bricking” or rendering devices non-functional, and often removes developer choice from the equation.

Outboard Firmware Update is a Notecard feature that allows device builders to implement OTA firmware updates in their devices without writing any code. Additionally, developers have the freedom of choice, and may select from a large number of microcontrollers (MCUs), programming languages, and real-time operating systems (RTOS), and can even perform updates on ‘native’ applications with no code from Blues and no RTOS at all.

Outboard Firmware Update is compelling for machine-learning projects like the one we’re discussing in this article, because it allows you update an app’s full ML model, and it allows you to do so remotely, and all without the risk of bricking your devices.

How does Notecard Outboard Firmware Update work?

The Notecard’s docs have a convenient checklist for everything you need to do to perform an outboard firmware update. Let’s look at how each item in that list works in this project.

You ensure your hardware is using the required wiring.

Because we’re using a Notecarrier F from the Blues Starter Kit for this project, all wiring between the Notecard and our host (the Blues Swan) is already ready to go. If you’re using other boards, see this guide for details on the required wiring.

You enable Notecard Outboard Firmware Update on your Notecard.

We’re performing the necessary call to make this happen in our Zephyr firmware. Specifically, the sample code performs a card.dfu request on the Notecard setting "name" to "stm32" (because the Swan is an STM32-based MCU), and "on" to true.

J *req = NoteNewRequest("card.dfu");
JAddStringToObject(req, "name", "stm32");
JAddBoolToObject(req, "on", true);
NoteRequest(req);

You build your firmware image file.

This step requires you to build the binary firmware image file you’d like to update your device with. In a production workflow, this step would occur after you have an updated version of your model ready, have placed the updated model into your application, and have done the necessary testing to push the model out to some, or all, of your devices.

For local testing, I’d recommend adding a simple logging statement near the top of main() so you can see the firmware update in action.

printk("[INFO] version: 2.0\n");

With the app updated you’ll need to build your Zephyr app, and then grab the built binary in your project from build/zephyr/zephyr.bin.

You upload your firmware on Notehub.

Once you have your new binary visit the Firmware section of your Notehub project, click the Upload firmware button, and upload your newly built file.

At this point Notehub has your firmware and is ready to push it out to your devices. To do so, go to your Notehub project’s Devices page, and then select the Host Firmware tab. Here you’ll see all available firmware versions for your host devices, and hitting Apply starts the process of getting the updated firmware on your host.

The Notecard downloads the firmware, verifies it, and performs the update.

Once you’ve queued up a firmware update in Notehub, the Notecard detects a new host binary is available on its next sync and downloads the firmware into its own flash storage.

The Notecard will then perform a RESET on the host microcontroller, which places it into its ROM bootloader. Then, using a microcontroller-specific communications protocol, the Notecard reprograms the various areas in flash as directed by instructions within the firmware image file, verifies them via MD5 hashes, and restarts the MCU.

The great thing is this all happens automatically, and at the end of the process your device will start running your updated model automatically.

Putting it all together

The big picture is each of the two processes discussed in this article—an easy way to collect ML training data from remote devices, and a workflow to remotely update your models—are both tools that can help you build a more robust MLOps process. The end goal is to avoid shipping your models once and forgetting about them, and to instead establish a process of continuously collecting data, and continuously improving the quality of the models you use for your production apps.

This article’s samples are reference implementations and are both available on GitHub. You may wish to use their code verbatim, or take the bits and pieces that make sense for your project.

At Blues we create a lot of real-world TinyML samples. If you found this discussion interesting, you might want to check out our ML accelerator projects, and the many ML projects our community have built. And if you have any questions about this post, or want to discuss anything further, check out our forum.

Should You Care About React Server Components?

TJ VanToll — Thu, 08 Apr 2021 14:39:40 +0000

Developers are busy people, and we don’t always have time to evaluate the JavaScript world’s myriad of frameworks and tools.

In this article I want to help you decide whether React Server Components is something that you should check out immediately, or whether you should wait.

We’ll start by looking at what React Server Components are, then discuss what problems they solve, and wrap up with a conversation on whether you should care or not. Let’s get started.

What are React Server Components?

React Server Components are a new experimental feature of React. Here’s how the React team describes the feature:

“Server Components allow developers to build apps that span the server and client, combining the rich interactivity of client-side apps with the improved performance of traditional server rendering.”

The client in the context of Server Components is a web browser. Although React can run in other clients—aka React Native running on iOS and Android—the Server Components feature is currently only concerned with the web.

The server in the context of Server Components is a JavaScript-based backend like Express.

The idea is, Server Components give you the ability to selectively move components from the client, where the browser executes them, to the server, where something like Express executes them.

To make it easy to tell the difference, Server Components introduces a new naming convention, where .server.js files are server components, .client.js files are client components, and regular .js files are files that can run in both environments. Here’s what that looks like in the React team’s Server Components demo.

Wait, why would I want to do any of this?

Rendering components on a server has a number of potential benefits. The React team’s full writeup on server components lists these benefits in great detail, but I’ll summarize what I think are the most important ones here.

Benefit #1: Using third-party dependencies without a file size penalty

One of best-known web performance tips is to minimize the amount of code you ship to your users. As such, front-end developers are hesitant to add large dependencies to their applications, even if those dependencies would save us a lot of time and effort.

Server Components offer an interesting solution to this problem. Because Server Components can live on a server (and not a client), their dependencies can live on the server as well—allowing you to use dependencies with zero impact on the size of your client-size bundles.

For example, suppose you’re writing an application that displays user-written Markdown. Two libraries that can help you do that are marked, which parses Markdown, and sanitize-html, which cleans up user-written HTML, including removing potential XSS attacks.

By using those two libraries you can write a simple React component that looks something like this:

/* RenderMarkdown.js */
import marked from 'marked'; // 35.9K (11.2K gzipped)
import sanitizeHtml from 'sanitize-html'; // 206K (63.3K gzipped)

export function RenderMarkdown({text}) {
  const sanitizedHtml = sanitizeHtml(marked(text));
  return <div>{sanitizedHtml}</div>
}

If you’re writing this component today you have to do a cost-benefit analysis. Are the conveniences of marked and sanitize-html worth the ~75K of gzipped JavaScript being added to your client-side bundle, as well as the performance hit of having your users’ browsers interpret an (un-gzipped) 200K+ of JavaScript code at runtime? Probably?

Now let’s look at a version of this component that can run on a server as a Server Component.

/* RenderMarkdown.server.js */
// Same code, but now these dependencies have no client-side penalty
import marked from 'marked';
import sanitizeHtml from 'sanitize-html';

export function RenderMarkdown({text}) {
  const sanitizedHtml = sanitizeHtml(marked(text));
  return <div>{sanitizedHtml}</div>
}

The only code difference in this version is the file name (RenderMarkdown.server.js instead of RenderMarkdown.js), but the behavior difference is fairly substantial. With this version of RenderMarkdown, your user never has to download or interpret marked or sanitize-html, but you still get the benefit of using both to keep Markdown implementation clean.

This is pretty cool, but before you get too excited, there are some Server Components limitations that will keep you from removing a lot of your client-side dependencies. Here’s the full of things a Server Component can not do from the React team’s Server Components RFC (Request for Comments).

The big ones here are Server Components cannot have state and cannot work with DOM APIs, which means all of your components that use things like useState() or onChange are not eligible. This is a big limitation because... most UI components rely on state and DOM APIs—meaning, a lot of your dependencies will have to remain on the client.

Still, being able to remove some of your code to the server has the potential to lead to noticeable performance gains, especially for larger apps. Facebook stated that their first production experiments with Server Components allowed them to remove almost 30% of their code from the client, which is a big deal.

And being able to move code to the server is not the only benefit of Server Components.

Benefit #2: Accessing your backend fast

Accessing data is one of the most expensive tasks in modern front-end applications. Because most applications store their data remotely (aka not on the client), getting the data you need involves network calls, and trying to reduce the number of network calls you make, while also keeping your code clean and maintainable, can be a big challenge.

Server Components have the ability to help here, as you now have the ability to move data-access components to a server, which can access data storage much faster.

For example, suppose you have a header component that needs to retrieve notifications, a user’s profile, and a user’s subscription. Here’s one way you could write that component today.

// Header.js
export function Header() {
  const [notifications, setNotifications] = React.useState([]);
  const [profile, setProfile] = React.useState({});
  const [subscription, setSubscription] = React.useState({});

  React.useEffect(() => {
    fetch('https://api.mycompany.com/notifications')
      .then(res => res.json())
      .then(data => { setNotifications(data); })
    fetch('https://api.mycompany.com/profile')
      .then(res => res.json())
      .then(data => { setProfile(data); })
    fetch('https://api.mycompany.com/subscription')
      .then(res => res.json())
      .then(data => { setSubscription(data); })
  }, []);

  return (
    <div>
      {...}
    </div>
  )
}

This approach is not ideal, as your component must wait for three separate network requests to completely render.

There are ways around this. You could ask a backend developer to build an API just for your header, which would return exactly what you need from multiple locations. But UI-specific APIs aren’t reusable, and therefore difficult to maintain over time. You could also use something like GraphQL to aggregate your backend API calls, but GraphQL isn’t an option for every company.

React Server Components offers an interesting new approach to this problem, by allowing you to access your data directly on the server. For example, consider this update to the header that lets you access a database right in your component.

// Header.server.js
import db from 'my-database-of-choice';

export function Header() {
  const notifications = db.notifications.get();
  const profile = db.profile.get();
  const subscription = db.subscriptions.get();

  return (
    <div>
      {...}
    </div>
  )
}

With Server Components, because you’re running on a server, you have the ability to access server-side resources without making a network round trip. And this ability lets you write cleaner code, as you don’t need to write a bespoke backend API just for the UI, or architect your components to reduce as many network calls as possible.

That being said, even though the ability to quickly access server-side resources is cool, it’s also not without downsides—the big one being, this is all highly dependent on your backend setup. You stand to gain a lot if your server-side resources are JavaScript-based, but if your server-side resources are in a completely different ecosystem (Java, .NET, PHP, etc), you’ll have a hard time actually gaining much from a Server Component architecture.

Before we wrap up let’s look at some of the other limitations of Server Components.

NOTE: I’m only hitting the high-level benefits of server components to keep this discussion brief. If you want to read about all the benefits, I’d recommend reading through the section on Server Components benefits from the React team’s RFC.

What are the issues with Server Components?

After spending time with Server Components my biggest complaint is the complexity it introduces to React applications.

For example, as I started to play around with the React team’s Server Components demo, I realized I had to fundamentally change how I approached building components. Instead of just creating a new file and typing export const MyComponent = () => {}, I now had to start thinking about how the component would be used, to help determine whether it was a better fit for the client or the server.

And that’s just when creating the components. As Server Components advance, some of those same concerns are going to apply to how you unit test your Server Components, and also how to debug these components when things go wrong.

For example, currently React Server Components return “a description of the rendered UI, not HTML”, which I’m sure is important to the implementation, but it does mean that the response you see in your developer tools looks like nonsense.

To be fair, most of these limitations come from Server Components being so new. The React team has stated that they expect most of the initial adoption to be through frameworks like Next.js early on, so it would make sense that some of these workflows are a bit rough today.

So should you care?

In my opinion there are a three groups of people that should care about Server Components today.

1) If you are a developer on a framework like Next.js.

Frameworks like Next.js are a logical consumer of React Server Components, as Next.js is already a framework that users server-side code to help React apps run faster.

These frameworks also have the ability to help hide some of the messy details of the underlying React implementation, making Server Components easier for your average developer to use.

2) If your company is operating at Facebook’s scale.

In its current state, React Server Components introduces a lot of complexity for small performance gains.

For companies like Facebook this sort of tradeoff makes sense, as they have the engineering capacity to deal with this complexity, and marginal performance gains are a big deal for web applications operating at Facebook’s scale.

That being said, most companies don’t operate at Facebook’s scale, and therefore most companies have no need to evaluate Server Components in its current state. You can wait until the feature stabilizes, or appears in a framework like Next.js

3) If you like tinkering with the latest and greatest.

The reason I looked into Server Components is I think they’re a cool idea with a lot of potential. The line between the client and server is getting blurry in the front-end world, and I think we’re going to see more experiments that try to mix and match the two environments to help developers build the best possible web applications.

With that in mind, if you’re the type of person that likes to experiment with the latest and greatest, React Server Components is well worth trying. The Server Components intro video is excellent, the React team’s RFC is a well-written guide that details how everything works. There’s also an open pull request where you can submit your own feedback on the feature.

Final words

Overall, Server Components is still too early for your average developer to care about, but it’s a fascinating idea with a lot of potential for those that want to guide the future of React and web development.

Master the Art of React UI with KendoReact

KendoReact is a professional UI components and data visualization library for React on a mission to help you design and build business apps with React much faster. With KendoReact, developers get an immediate productivity boost and businesses get shorter time-to-market. Designed and built from the ground up for React, KendoReact plays well with any existing UI stack. Its 90+ customizable and feature-rich components make it the perfect foundation for your internal UI library.

Built by a team with 19+ years of experience in making enterprise-ready components, this library is lightning fast, highly customizable and fully accessible, delivering support for WCAG 2.1, Section 508, and WAI-ARIA a11y standards. You can find detailed accessibility compliance information here.

My Top 5 Tech Speaking Tips

TJ VanToll — Wed, 21 Aug 2019 18:44:41 +0000

This article is an eclectic set of speaking tips I’ve learned from giving dozens of tech talks at conferences around the world. I hope these tips help new speakers prepare their first talk, and help give experienced speakers ideas to potentially improve.

One thing I’ll note though: these are tips that I’ve found work for me, which doesn’t necessarily mean they’ll work for you. Each speaker needs to find their own style and workflow, so try to take inspiration from these tips and don’t interpret them as hard and fast rules.

With that disclaimer out of the way, on to the tips!

Tip #1: Don’t worry about slide design
Tip #2: Make an outline
Tip #3: During slide creation, make your intro slides last
Tip #4: Make the audience do stuff
Tip #5: Speak—a lot

Tip #1: Don’t worry about slide design

I’ve never cared about slide design and you probably shouldn’t either.

I offer this as a tip because I find that new speakers spend a lot of time trying to find a good color scheme or font for their slides. Or get confused about whether to use PowerPoint, or Keynote, or something web-based.

You don’t want this sort of thing to get in your way. Start with a tool you like (for me that’s PowerPoint because it’s simple), pick the blank slide template, and get started.

Just to give you an idea, I typically have three types of slides that I use.

Design #1: Plain text

I use simple slides with just text on them a whole lot. For colors I use black text on a white background for readability, and I use the Avenir font—but only because that was the font on some slide deck I started with years ago. It looks nice to me though.

Design #2: Screenshots

For a lot of my slides I just take a screenshot of something and then just toss it on a slide. It works.

Design #3: Bullets

I use bulleted slides when I need to present a list, and I just use the default PowerPoint design for this.

I do occasionally mix things up, but that’s the approach I take on 95% of the slides I make. And for most cases that’s all you’ll need as well.

Unless you’re an actual designer and want to spend the time to create something really unique, I’d encourage you just to pick the blank slide deck in your tool of choice and call it good enough.

My second tip deals with what to do next.

Tip #2: Make an outline

I make an outline for every talk I give. The outline is dead simple, and includes only three things: the talk’s main audience takeaway, 3–4 topics that help support that takeaway, and an actionable next step.

When written out that structure looks something like this.

State the takeaway, aka what I want the audience to get out of the talk.
Topic #1
Topic #2
Topic #3
Topic #4 if necessary
Restate the takeaway again
Give an actionable next step

For example, below is the outline I had for a Is Augmented Reality the Future? talk I recently gave in Montreal.

Takeaway: AR (Augmented Reality) is cool, but still pretty hard for your average developer.
Topic #1: History of AR
Topic #2: AR today
Topic #3: Building AR apps
Restate the takeaway
Provide my preferred place to get started building AR apps.

Once I have this outline I start including the outline in my slide deck directly. Specifically, I create a slide called “Agenda” that looks something like this.

This act of creating an outline helps you organize the talk in your head, and placing that outline in slides helps you visually see your progress creating content for each topic. Audiences like structure as well, as it helps them know what to expect from your talk, and therefore makes it easier for them to follow along.

To make it even easier for the audience, I always include the same agenda slide in my deck when I transition between topics. For example, after I complete the “Brief history of AR” topic I show the slide below.

These slides give me a logical place to summarize the previous topic and segue to the next.

Next, I create a slide that summarizes the key takeaways of my talk at the beginning and end of my talk. Here’s what that slide looked like for my AR talk.

When I show this slide at the beginning of my talk I say something like, “This is what I plan to prove/show you today”, and at the end I restate the points, and usually talk about how the topics I presented support those points.

Once you have this basic outline in place you’re ready to start developing your introduction and your main content.

Tip #3: During slide creation, make your intro slides last

When creating slides most people start with the introduction, because, well, it’s the first thing you actually present. The problem is that creating compelling introductions can be hard, even for experienced speakers.

And because of this, it’s really easy to waste a lot of time searching for the perfect way to introduce your topic, when in reality it’s fairly insignificant.

Your introduction can be as simple as stating the following points, especially when you’re just getting started.

I’m <your name>.
State topic
State audience takewaways
Show agenda
Start talking about topic 1.

By saving the introduction until the end you’ll have a better idea of what you might want to say to start your talk with. You can also rest assured that the bulk of your work is done.

All that being said, I don’t mean to imply introductions aren’t worth spending any time on, because done well they can be way to engage the audience and draw them into your talk. I would just save them for last.

When you do create an introduction you need to experiment a bit and find what works for you. My go-to introduction is to telling a story that relates to my topic or the place I’m speaking. For example, to open my AR talk I told a story about my love for Pokémon GO, and how that’s what got me interested in AR in the first place.

I was lucky enough to give a talk in Denmark last year, and I opened with a slide with pictures of me around the area for fun.

If you have an idea for a story to tell I’d encourage you to take it and run with it. Deliver the story with confidence and have fun.

But if you don’t have an idea don’t worry either. Save the intro for the end, and if you can’t think of anything, stick with the basics and get into the meat of your talk right away.

And when you’re delivering the bulk of your content I have a tip for that as well.

Tip #4: Make the audience do stuff

Walk into a room halfway through a random tech talk and you’ll likely see at least half the attendees looking at their phones or laptops.

The thing is, it’s hard to keep people’s attention on anything, and tech topics aren’t the world’s most engaging material. As a speaker there are a few things you can do to help keep your audience’s attention.

The simplest thing you can do is poll your audience at given points in your talks. I often do this before I introduce a new topic. For example, in a talk I recently gave called One Project. One Language. Three Apps. I used the slide below to introduce two frameworks, NativeScript and React Native.

Before I introduced each framework I asked the audience, “How many people here are familiar with React Native”, and then, “How many people here are familiar with NativeScript”.

These simple questions accomplish two things. First, it forces the audience to look up and engage with the talk, if only for a minute. Second, it helps me get a read on the room. If I see 5% of hands go up I know I need to give a thorough introduction, whereas if every hand goes up, I know a short explanation will suffice.

Polling the audience is the easiest way to engage the audience, but there are a variety of more creative ways you can accomplish the same goal.

For example my significant other gives talks on CSS, and one fun thing she does is include mini quizzes in her slides, like the one below.

This again solves multiple goals. First, it forces the audience to not only pay attention, but to also really try to understand the content to get the correct answer. (It’s 600px, by the way.)

Second, it gives the presenter a good sense of whether the audience is following along with the content. If you see a lot of hands going up and a lot of correct answers you know people are understanding your material.

There are professional tools out there to make this sort of audience quizzing even more engaging. For example the service Kahoot! makes it easy to configure quizzes that an audience can easily complete on their laptops and smartphones.

Overall, the specific tool or approach doesn’t really matter. What does matter is finding some way to break up the inherent monotony of a tech talk by engaging the audience.

Tip #5: Speak—a lot

The phrase practice makes perfect applies more to public speaking than any other life skill. No amount of practicing in front of a mirror will prepare you for the experience of delivering a talk in front of a live audience, and the only best way to improve is continue to do just that—deliver talks, repeatedly.

This doesn’t mean you have to constantly give talks at conferences around the world though. Occasionally giving a presentation at a local user group, or for a few coworkers at work, will help you learn how to be in front of an audience and deliver your material effectively.

As you get more comfortable speaking you’ll want to work on how to improve the quality of your talks. And for that I have two recommendations.

Watch yourself on video

Most people would choose elective surgery over watching a video of themselves presenting—myself included. But it’s extremely important, as you’ll learn things about your talks you can only see from a third-person perspective.

Personally I started as a heavy “um” user, which I had no idea about until I saw myself on video. Later, I developed a habit of using my hands... a lot. It was awkward. But knowing these tendencies helps me consciously think about avoiding these habits, and ultimately helps me stop repeating them in the future.

It’s important. Get a friend to record you and watch the video. You’ll hate it, but it’s worth it. Promise.

Find a trusted friend for feedback

In addition to watching yourself speak, it’s good to get feedback from others as well. However here you have to be extremely careful for two reasons.

Reason #1: Some people are horrible, and will leave negative feedback on your talk for silly reasons, like not liking the framework you’re using (seriously).

And even if you know the feedback is unreasonable, the human brain has an unfortunate tendency to fixate on the negative, even if you get an onslaught of positive feedback to go with it.

And I can say this from many personal experiences. Remember the talk I mentioned earlier that I gave in Denmark? It’s the most well received talk I’ve ever given. I’ve had random people at conferences compliment me on it; it’s shown up in all sorts of positive tweets, and has gotten numerous mentions in popular newsletters and such.

This was great, until I made the classic mistake of reading the negative comments on the YouTube recording, which if I’m honest, has ruined a lot of the positive experience I had from preparing and delivering that talk.

Overall, be careful asking for feedback broadly because the human brain has the not-at-all-useful tendency to heavily focus on the negative.

Reason #2: Most people won’t be honest. If you deliver a talk to a group of friends or coworkers and ask for feedback, the vast majority of people will reply with something like “It was good.” or “I liked it.”.

Although this is supportive, it’s also good to get honest feedback on how you can improve. For this you need to find that blunt person in your life that’s not afraid to tell you like it is, and will call you out on things you can improve on.

The big difference between asking a friend and random people is a friend can provide context and details on things you need to work on. There’s a big difference between “That talk sucked” and “I had trouble following along in the middle part of the talk. I think you could have explained the concepts better or maybe used more examples to prove your points.”

You can also ask questions of your friend, like “did you understand the first topic?”, or “did I use my hands too much?”.

If you’re having trouble finding that blunt person in your life try being blunt yourself. I find that people that give generic “it was good” feedback find much more to say if you press them.

Final tip: Just do it!

Ok that’s it for now. I have a lot to say because speaking has been very important to me over the last 6–7 years of my life, and it’s opened up a ton of opportunities that I wouldn’t have had otherwise.

Hopefully you found these tips helpful. If so let me know, because I could easily come up with 5 more 😉

TIP: If you want to see me speak in person I’ll be at DevReach in Sofia, Bulgaria in October, and at at jsMobileConf in Boston in November. Both are great events.

Why ‘Sign in with Apple’ is Actually Pretty Great

TJ VanToll — Tue, 02 Jul 2019 16:29:41 +0000

I believe that Apple’s recently announced ‘Sign in with Apple’ workflow is an important step for improving the security and usability of login screens.

In this article I’ll explain what ‘Sign in with Apple’ is, why I believe it’s a great thing for users, the drama around Apple’s implementation, and some of the lingering concerns I have.

The crux of my argument is that Apple’s new workflow provides badly needed innovation for a process everyone hates—logging in. Even if Apple’s implementation is flawed (which we’ll get to), hopefully this effort will spur other ideas from other tech giants in response, ideally making the login process better for everyone. To show what I’m talking about let’s start with a bit of background.

Why passwords are the worst

A 2018 survey done by LastPass showed that 59% of people always or mostly use the same password—everywhere. The same study found that 45% of people don’t bother changing their password when their accounts get hacked, and that 42% of people keep passwords in a file, like, a Word doc or Excel spreadsheet.

As I write this article, the top-selling book in Amazon’s “Internet & Telecommunications” category is the internet address & password logbook. Sixth place in the same category is the INTERNET PASSWORD LOGBOOK, which honestly has a nicer design than the top seller.

We have failed. Failed hard.

As easy as it is to mock books like this, it’s important to remember that these books are solving a real problem. Using unique passwords is important, but remembering multiple passwords in your head is impossible, and not everyone has the money and tech savviness to use a password manager.

Funnily enough, you can make a compelling argument that physical-password-book users are more secure than password reusers, assuming the physical-password-book users create unique passwords for each service they use.

Regardless, the sheer existence of these books is indicative of just how broken the login process is for most users today.

Making login better

Everyone knows the current way we log in is not ideal, and plenty of tech companies have tried to make this process better. One big improvement to login screen usability was the advent of Single Sign-On, wherein the user uses a single account to authenticate with multiple apps or services.

An example of Single Sign-On in an iOS app. The user can use Google or Facebook to authenticate.

The main appeal of SSO is that users don’t have to create and remember a new set of credentials, allowing them to maintain a one-password lifestyle, without the normal downsides of password reuse.

However, despite its appeal, SSO has its drawbacks as well. Specifically, most SSO providers require that you provide your email address (and sometimes other information as well) to the service you’re authenticating with.

While providing an email address seems innocuous, shady services will often sell lists of email addresses to advertisers or spammers, greatly increasing the spam mail you have to deal with. Far worse, even if a service has no malicious intentions, data breaches can expose your email to hackers worldwide, opening up the possibility of attacks on accounts you’ve created around the Web with that same email.

Enter Apple

With this backdrop in mind, earlier this month Apple announced a new ‘Sign in with Apple’ feature that, at first glance, works very similarly to the SSO mechanisms from Google, Facebook, and others that thousands of apps use today.

However, Apple’s new authentication workflow offers one innovative twist: when you sign in with Apple, you get to choose whether you want to share your email with the service you’re signing up for, or, whether to hide it from that service.

An example of ‘Sign in with Apple’ in action in a sample app.

If you choose to hide your email, Apple will create a randomly generated Apple-hosted email address, which will receive all messages on your behalf, and forward them to your legitimate email address.

This workflow alleviates many of the privacy concerns associated with similar SSO solutions from companies like Google and Facebook. If a shady service sells your email to an advertiser, you’ll be able to easily turn off email forwarding to stop the unwanted spam. Even better, if your generated email address gets exposed in a data breach, you can rest assured, as your Apple-generated email address is unique, therefore hackers will be unable to use that address in subsequent attacks.

It’s an elegant solution to a common problem; a solution that the likes of Google and Facebook might be hesitant to replicate, because each are companies that earn the bulk of their revenue from advertisers—advertisers that very much like to track users by their email address around the Web. Because Apple does not rely on a similar revenue model, they’re uniquely positioned to innovate and offer users a privacy-focused authentication option. That being said, Apple is not without its own motives.

The drama

Apple has a vested interest in being seen as a privacy-focused company, therefore, for them, creating and promoting the ‘Sign in with Apple’ workflow makes a lot of sense.

More interesting is the news that broke shortly after WWDC, when developers found documentation that stated Apple will require apps that support third-party logins to provide a way to sign in with Apple. Here’s the exact wording from Apple’s site.

“Sign In with Apple will be available for beta testing this summer. It will be required as an option for users in apps that support third-party sign-in when it is commercially available later this year.”

This controversial decision immediately sparked a heated debate in the tech world. Those against Apple’s decision argued that Apple is using their monopolistic control over the iOS platform to advance their own SSO solution.

Leveraging their position as gated community guard to push their own single sign on product? Yeah, thats going to get looked at by the EU at the very least. Doesn't matter if its an additional option or not, the fact that its required is enough...
— Richard Price (@richardprice) June 3, 2019

woah. It is "walled garden" moves like this that make me glad I write web apps.
— Jared Beck (@jaredowenbeck) June 3, 2019

Monopolist gonna monopolist
— Caitlin Fitzharris (@caitlintackles) June 5, 2019

The timing is indeed interesting, as Apple is actively being sued by developers and consumers for its App Store policies. You might think the company would avoid potentially monopolistic moves while other parts of iOS have active anti-trust lawsuits pending—but apparently Apple isn’t worried, or they don’t believe their actions here are monopolistic.

On the other side of the argument, those in favor of Apple’s decision to require ‘Sign in with Apple’ argue that Apple has to require their new workflow for apps to actually use the feature.

The problem "Sign In With Apple" is that it's so delightfully privacy-safe that developers won't offer it. They crave your real email address for reengagement campaigns. Fb happily provides it.
— Josh Constine (@JoshConstine) June 3, 2019

Seems like it'd have to be. Otherwise it'd share the same fate as all that BrowserID, OpenID kinda stuff. I think apps often support SSO because they want the data that comes with it. Most were never interested in supporting an option that didn't come with the data.
— Moxie Marlinspike (@moxie) June 4, 2019

This side of the argument is compelling. For better or worse, there’s very little incentive for individual apps to implement privacy-focused features for users, so it stands to reason that most would just ignore Apple’s new API if they could.

Remember BrowserID? It was a feature championed by Mozilla to provide SSO across the web using your email address. It was a great idea, and had some real benefits for users, but it never took off because very few developers actually integrated it.

If you’re an app maker, why would you implement BrowserID or ‘Sign in with Apple’ when you have a roadmap full of backlogged tasks? Moreover, the Apple-based workflow aims to prevent your service from gathering user data—data that all marketing and sales departments will have a hard time giving up unless forced.

So although ‘Sign in with Apple’ isn’t perfect, and although it’s concerning to give Apple even more control over iOS users, at least the mandate will force all apps that use third-party logins to seriously reassess how they handle their user’s data.

The broader point

More broadly speaking, my hope is that Apple’s push here will lead to further advancements into the password management world. It’s 2019 and most people are buying password managers, buying books to write down their passwords, or just giving up and logging in with their cat’s name across the Web. I think we have every right to demand more of the tech giants to help fix this.

For example, both Google and Facebook claim to care about their users’ privacy, and both have the resources to create similar systems, so why shouldn’t we demand they provide a way to authenticate into third-party apps with similar privacy protections? Better yet, what if a tech company reimagined a BrowserID-like solution that avoids one company having total control?

There’s no easy win here, but hopefully Apple’s assertive move will spark innovations that move user security and privacy forward.

At Progress we already have you covered to work with Apple’s new APIs. NativeScript users can start experimenting with ‘Sign in with Apple’ today with the new nativescript-apple-sign-in plugin.

And because ‘Sign in with Apple’ is based on OAuth 2.0, Kinvey users will be able to work with Apple’s new workflow with Kinvey’s Mobile Identity Connect later this fall.

What the Apple Supreme Court Decision Means for Developers

TJ VanToll — Thu, 16 May 2019 13:14:08 +0000

Earlier this week the US Supreme Court allowed an antitrust lawsuit against Apple to proceed. If you’re like me this decision sounded super important... but also super confusing.

To try to clear things up, in this article, we’ll break down what this ruling means for your average developer, the ruling’s effect on the iOS ecosystem, and the ruling’s implications on the future of mobile development.

What does the ruling mean?

Let’s start with a little background. If you develop an app for the iOS platform, the only way to get that app to users is through the iOS App Store, and Apple takes a 30% cut of all transactions that occur there. That cut ends up being incredibly lucrative for Apple, as App Store revenues were a staggering 46.6 billion dollars in 2018.

This court case calls Apple’s app-distribution model into question. Specifically, the case’s plaintiff alleged that, by requiring iOS users to buy apps exclusively from the App Store, and taking a 30% commission on all transactions that occur there, Apple is adding a fee that developers pass on to customers. Simply put, the plaintiffs claimed that Apple is using their monopoly over app distribution to raise prices for iOS customers.

Apple’s counterargument was that iOS users buy apps from developers and not Apple, and therefore Apple is not subject to some complicated provisions of US antitrust laws. (The specifics involve a 1970s legal doctrine called Illinois Brick and a kind-of confusing “indirect purchaser” discussion. Being a lawyer must be so fun.)

The court ruled against Apple, and in a 5–4 decision, allowed iOS customers to sue Apple for allegedly driving up prices of iOS apps.

What effect does this ruling have?

Let’s start with one important point: this ruling only allows iOS customers to sue Apple for their app-distribution business model; it did not rule that the App Store violates anti-trust law. However, this ruling clears the way for legal proceedings that attack the App Store’s business model directly, which could force Apple to fundamentally change the way app distribution on iOS works.

That being said, it’s possible (likely even) that the subsequent cases that challenge this model will take years to play out. After all, the initial court procedures that started the just-resolved case were made in December of 2013. Therefore, don’t expect this ruling to have any short-term effect on way you build and distribute iOS applications.

One reason the proceedings may take longer than expecting is dealing with the finer points of the law. For example, suppose the court rules that Apple’s model indeed violated anti-trust policies, and consequently raised prices for consumers. How do you determine the amount prices were raised? And who does the extra money go to? Customers? Developers? The current suit was done on behalf of customers, but it’s very possible that a class-action lawsuit on the behalf of developers could complicate the issue.

Long term, if legal restrictions do come down on Apple they’re likely positive effect on iOS developers. We might see a future where Apple is forced to permit third-party app stores, or to provide ways for users to side load apps—each of which would give developers more control in how they get their apps to their users.

Interestingly, these changes would make iOS work a lot more like Android, which already allows for alternative app stores and side loading, and is therefore not subject to these legal actions.

The ruling’s broader effect on the software world

Although these court proceedings have centered around Apple, this ruling has consequences that could extend to software distribution on other platforms, because there are a lot of platforms that have monopolistic control over app distribution that you might not think about.

Consider Rokus, Fire TVs, and basically all smart TVs platforms. In each of these, the only way to get apps is through a single vendor-controlled store.

Here’s another interesting one: Microsoft recently announced an Xbox that doesn’t come with a disc drive. Presumably the only way to purchase games for this new Xbox will be through a Microsoft-provided store; therefore, does that new Xbox violate US anti-trust law?

These cases will depend on how each platform makes money. For example, if Microsoft doesn’t make any additional money from digital purchases, there’s not much reason for developers or customers to file a lawsuit. But the court’s recent decision does open the door for class-action lawsuits against platforms with a business model similar to Apple’s.

Quick takeaways

If you’re still confused by all of this here’s a quick wrap up: the US Supreme Court ruled that customers have the ability to sue Apple for its monopolistic control over iOS app distribution, alleging that this monopoly unfairly raises prices for consumers.

This ruling doesn’t have any immediate effect on iOS users or developers, but it allows for further lawsuits to proceed—lawsuits that could fundamentally change how iOS app distribution works, and could have a broader effect on how all platforms control app distribution.

How to Build a PWA, an iOS App, and an Android App—From One Codebase

TJ VanToll — Tue, 30 Oct 2018 14:44:51 +0000

I have a long history of choosing between web and native, often wrongly. I’ve built web apps that were scraped for native apps, and I’ve wasted time building native apps that found no audience.

In my current job as a mobile-focused developer advocate at Progress, I talk to developers that regret their web or native decision every week. Sometimes you don’t realize you need a native app until you hit the limitations of the web, and conversely, sometimes you realize a web app meets your needs only after you’ve went through the lengthy process of building multiple native apps.

The good news is JavaScript developers no longer have to make this difficult choice. Through the use of the recently announced NativeScript and Angular integration, it’s now quite easy to build a PWA (Progressive Web App), a native iOS app, and a native Android app from one codebase.

In this article I’ll show you how it works. You’ll learn the steps you’ll need to take to build for all three platforms, as well as some tips and tricks I learned from going through this process myself.

What you’re building

Over the last month I built a Pokémon-based checklist app and deployed it to Google Play, the iOS App Store, and the web. The app is a purposely simple app designed to help teach how the NativeScript and Angular technology stack work.

For this article I’ll walk you through building a similar checklist-style app that looks like this.

Feel free to follow along as a way of starting your own code-sharing application, or to just browse the code to get a high-level idea of how this whole process works.

Starting your app

When you’re ready to build, your first step is to install the Angular CLI, NativeScript CLI, and NativeScript schematics, all of which are available on npm. Open your terminal or command prompt and run the following commands.

npm install -g @angular/cli
npm install -g nativescript
npm install -g @nativescript/schematics

Here’s what these tools do.

The Angular CLI is a command-line interface for building and running Angular apps.
NativeScript is an open-source framework for building iOS and Android apps with JavaScript or TypeScript.
NativeScript schematics is an Angular CLI extension that adds the ability to do NativeScript-related things. As you’ll see in a minute, this is what makes it possible to run your Angular apps on iOS and Android.

With installation out of the way, your next step is to create an app. To do that, run the following command from your terminal or command prompt.

ng new Checklist --collection @nativescript/schematics --shared --sample

Let’s break down what’s happening here.

ng new is the Angular CLI command you use to start new Angular apps.
Checklist is your app name. For you own apps you’ll want to provide your own value here.
The --collection @nativescript/schematics flag tells the Angular CLI about NativeScript schematics, which makes it possible for this app to run on iOS and Android through NativeScript.
The --shared flag tells NativeScript schematics you wish to start with a code-sharing project template.
The --sample flag has NativeScript schematics scaffold a few sample components which we’ll look at momentarily. You’ll want to omit this flag when you go to build your own apps.

Now that you have an app let’s look at how to run it.

Running your app

First, cd into the new app you just built.

cd Checklist

Next, run npm install to install your app’s required dependencies.

npm install

From here there are three different commands you can use to run your app.

First, ng serve is how you run your newly created app on the web. Go ahead and run this command from your terminal or command prompt.

ng serve

After the command finishes, you’ll see a message about an Angular Live Development Server listening.

If you follow the instructions and visit localhost:4200 in your browser you’ll see the default web app running, which is a simple master-detail app showing soccer players.

If you’ve done any Angular development before this will feel very familiar, as it’s the same workflow you use to build Angular web apps—which is cool!

But of course you’re not building only for the web with this workflow, and the real magic happens when you bring NativeScript into the picture.

But before you run this app on iOS and Android there’s one warning I need to give: because NativeScript apps are truly native iOS and Android apps, there are an additional set of system requirements you need to install on your development machine to build these apps. Check out this page on the NativeScript docs for the necessary setup steps you’ll need to complete.

NOTE: The next version of NativeScript, NativeScript 5.0, has some fun changes that will allow you to run apps without any local setup. You can learn more on GitHub.

With the setup out of the way, return to your terminal or command prompt, use Ctrl + C to stop your ng serve command, and next execute npm run android. The command will take a minute to run, as under the hood NativeScript is building a completely native Android app. When it finishes you’ll see the following screen.

If you’re developing on macOS, you can also try running npm run ios, which runs through a similar process, but instead builds and starts your app on iOS. When it finishes you’ll see this screen.

With a single codebase and a set of straightforward commands you now have the same app running in three places.

Cool, huh?

Now that you know how to run your app, let’s dig into your app’s code to see what’s going on.

Looking through the code

Starting at the root of your project, here are the top-level folders you need to know about.

Checklist/
├── App_Resources
├── platforms
└── src

The App_Resources folder is where NativeScript stores iOS and Android configuration files and image resources, such as your app’s icons and splash screens. Later in your app development, you’ll want to switch to your own image assets using the NativeScript CLI’s tns resources generate command.
The platforms folder is where NativeScript stores your generated iOS and Android apps; you can think of it as a dist folder for your native projects.
The src folder is where your source code lives, and it’s where you’ll be spending 95% of your time.

NOTE: There are a bunch of other configuration files in the root folder, such as an angular.json file for Angular CLI customization, a package.json file for managing dependencies, and a series of tsconfig.json files for configuring TypeScript. When getting started it’s best to leave these files alone; you can come back to them later and customize them to meet your project’s needs.

Since the src folder is where you’ll be spending most of your time, let’s dig into the contents of that folder in more detail.

src/
├── app
│   ├── app.component.css
│   ├── app.component.html
│   ├── app.component.tns.html
│   ├── app.component.ts
│   ├── app.module.tns.ts
│   ├── app.module.ts
│   ├── app.routes.ts
│   ├── app.routing.tns.ts
│   ├── app.routing.ts
│   └── barcelona
│       └── ...
├── app.css
├── assets
├── index.html
├── main.tns.ts
├── main.ts
├── package.json
└── styles.css

If you’ve built Angular web apps before a lot of this structure will look very familiar. All Angular apps have a main.ts file for initialization, an app.module.ts file for module declarations, a series of app.routing.ts files for setting up routing, and an app.component.ts file to use as the app’s first component.

TIP: If you’re new to Angular and would like a more in-depth introduction to these concepts, check out the Angular quick-start tutorial. All of the concepts you learn there directly apply to the code-sharing structure in this article.

One concept unique to NativeScript’s code-sharing workflow is the .tns naming convention you see on some of your app’s files (for example app.routing.tns.ts).

By default, NativeScript schematics includes all your project’s files in both your web and mobile apps—after all, you are trying to share code. However, in certain situations you will need to create web- and mobile-specific files, and that’s where the .tns extension comes in.

For example, take the app.module.ts and app.module.tns.ts files. When you run your app on the web, the Angular CLI uses your app.module.ts file as you’d expect. However, when you run your app on iOS or Android, NativeScript schematics instead grabs and uses your app.module.tns.ts file. This convention is a powerful way to split your web and mobile code as necessary, and you’ll use it frequently as you build your own apps using this setup.

Now that you have a bit of background on how your project is structured, let’s build something new.

Building your web UI

In the starter app, the vast majority of your code is in a src/app/barcelona folder, as that’s the code that builds up the player list you saw in your app earlier. In this section you’re going to create a brand-new component for the web, and in the next section, you’ll see just how easy it is to get that same component working in a native iOS and Android app.

Let’s start by scaffolding some files. To do so, start by using the cd command to navigate to your src/app folder.

cd /src/app

Next, make a new folder named list, and create the following files in that folder.

. app
└── list
    ├── list.common.ts
    ├── list.component.css
    ├── list.component.html
    ├── list.component.ts
    ├── list.module.ts
    └── list.service.ts

TIP: When you get more comfortable working with NativeScript schematics, there are a series of commands you can use to help generate components and modules. See the NativeScript schematics documentation for more information.

Here’s what to put in those files as a first step. Don’t worry too much about exactly what this code is doing, as we’ll discuss the important things to note momentarily.

list.common.ts

import { Routes } from '@angular/router';

import { ListComponent } from './list.component';
import { ListService } from './list.service';

export const COMPONENT_DECLARATIONS: any[] = [
  ListComponent
];

export const PROVIDERS_DECLARATIONS: any[] = [
  ListService
];

export const ROUTES: Routes = [
  { path: 'list', component: ListComponent },
];

list.component.css

ul {
  list-style: none;
  padding: 0;
  margin: 0;
}

li {
  border-style: solid;
  border-width: 0 0 1px 0;
  border-color: #C0C0C0;
  display: flex;
  align-items: center;
  cursor: pointer;
}

li.selected {
  background-color: #C0C0C0;
}

img {
  height: 96px;
  width: 96px;
}

list.component.html

<ul>
  <li *ngFor="let item of items" [class.selected]="item.selected" (click)="itemTapped(item)">
    <img [src]="item.image">
    <span>{{ item.name }}</span>
  </li>
</ul>

list.component.ts

import { Component, OnInit } from '@angular/core';

import { ListService } from './list.service';

@Component({
  selector: 'app-list',
  templateUrl: './list.component.html',
  styleUrls: ['./list.component.css']
})
export class ListComponent implements OnInit {
  items: any[];

  constructor(private listService: ListService) { }

  ngOnInit() {
    this.listService.get().subscribe((data: any) => {
      this.items = data;
    });
  }

  itemTapped(item) {
    this.listService.toggleSelected(item);
  }
}

list.module.ts

import { NgModule } from '@angular/core';
import { CommonModule } from '@angular/common';
import { HttpClientModule } from '@angular/common/http';
import { RouterModule } from '@angular/router';

import { ROUTES, COMPONENT_DECLARATIONS, PROVIDERS_DECLARATIONS } from './list.common';

@NgModule({
  imports: [
    CommonModule,
    HttpClientModule,
    RouterModule.forRoot(ROUTES)
  ],
  exports: [
    RouterModule
  ],
  declarations: [
    ...COMPONENT_DECLARATIONS
  ],
  providers: [
    ...PROVIDERS_DECLARATIONS
  ]
})
export class ListModule { }

list.service.ts

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { map } from 'rxjs/operators';

@Injectable()
export class ListService {
  saved: any[];

  constructor(private http: HttpClient) {
    let saved = localStorage.getItem('items');
    if (saved) {
      this.saved = JSON.parse(saved);
    } else {
      this.saved = [];
    }
  }

  get() {
    return this.http.get('https://rawgit.com/tjvantoll/ShinyDex/master/assets/151.json')
      .pipe(
        map((data: any) => {
          const returnData = [];
          data.results.forEach((item) => {
            item.selected = this.saved.indexOf(item.id) != -1;
            returnData.push(item);
          })
          return returnData;
        })
      );
  }

  toggleSelected(item) {
    if (item.selected) {
      this.saved.splice(this.saved.indexOf(item.id), 1);
    } else {
      this.saved.push(item.id);
    }

    item.selected = !item.selected;
    this.save();
  }

  save() {
    localStorage.setItem('items', JSON.stringify(this.saved));
  }
}

Again, don’t worry if you don’t understand everything that’s going on in this code. For now, all you need to know is that this is a fairly straightforward Angular component that loads data from an API and shows it in a list.

To activate this new component so you can try it out, first, add this new component to your app.module.ts file so Angular knows about it. Here’s what your new app.module.ts file should look like.

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { AppRoutingModule } from './app.routing';
import { AppComponent } from './app.component';
import { ListModule } from './list/list.module';

@NgModule({
  declarations: [
    AppComponent,
  ],
  imports: [
    BrowserModule,
    AppRoutingModule,
    ListModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Next, change the default path in your app.routes.ts file, so Angular navigates to the new list component by default. The new app.routes.ts file should look like this.

import { Routes } from '@angular/router';

export const ROUTES: Routes = [
  { path: '', redirectTo: '/list', pathMatch: 'full' },
];

Finally, just so this app looks a little nicer, paste the following code in your src/styles.css file, which is the place you add global CSS for your Angular apps.

html, body { margin: 0; }
body {
  font-family: -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;
}

With this in place, return to your terminal or command prompt and run ng serve. After the command runs, open your browser and visit localhost:4200, and you should now see a simple little checklist that looks like this.

The app you now have is a really simple app that allows users to select items. If you look at the code in list.service.ts, you can see that the app also remembers the user’s selections using localStorage—meaning, all selections remain when the user returns to the app.

At this point you have a very simple mobile app. If you’d like, you could follow one of many online guides for giving this app a service worker and making it into a Progressive Web App—after all, at the moment you’re just using the Angular CLI to build a web app.

The real fun of this workflow though is in just how easy it is to turn a functional app like this into a native iOS and Android app. Let’s look at how to do that.

Creating your iOS and Android app

When converting a web interface to mobile using NativeScript schematics, your first task is to identify which code you can reuse and which code you cannot. Let’s return to the list of files that make up this component.

. app
└── list
    ├── list.common.ts
    ├── list.component.css
    ├── list.component.html
    ├── list.component.ts
    ├── list.module.ts
    └── list.service.ts

For this example you’ll need to create a NativeScript-specific markup file (.html), styling file (.css), and module file (.module.ts). To do that, to ahead and create three new files, list.component.tns.css, list.component.tns.html, and list.module.tns.ts. Your file tree should now look like this.

. app
└── list
    ├── list.common.ts
    ├── list.component.css
    ├── list.component.html
    ├── list.component.tns.css (new)
    ├── list.component.tns.html (new)
    ├── list.component.ts
    ├── list.module.ts
    ├── list.module.tns.ts (new)
    └── list.service.ts

Remember that the Angular CLI will automatically grab the code in your .tns.* files when building for NativeScript, and your non-.tns files when building for the web. Therefore, the .tns files are where you need to put your code that’s specific to NativeScript.

To do that, start by opening your list.module.tns.ts file and paste in the following code.

import { NgModule, NO_ERRORS_SCHEMA } from '@angular/core';
import { NativeScriptCommonModule } from 'nativescript-angular/common';
import { NativeScriptHttpClientModule } from 'nativescript-angular/http-client';
import { NativeScriptRouterModule } from 'nativescript-angular/router';

import { ROUTES, COMPONENT_DECLARATIONS, PROVIDERS_DECLARATIONS } from './list.common';

@NgModule({
  imports: [
    NativeScriptCommonModule,
    NativeScriptHttpClientModule,
    NativeScriptRouterModule,
    NativeScriptRouterModule.forRoot(ROUTES)
  ],
  exports: [
    NativeScriptRouterModule
  ],
  declarations: [
    ...COMPONENT_DECLARATIONS
  ],
  providers: [
    ...PROVIDERS_DECLARATIONS
  ],
  schemas: [
    NO_ERRORS_SCHEMA
  ]
})
export class ListModule { }

You need a NativeScript-specific module file so that you can declare NativeScript-specific imports, such as NativeScriptHttpClientModule, and NativeScriptRouterModule. However, note how both your list.module.ts and list.module.tns.ts files pull routes, declarations, and providers from your list.common.ts file. This gives you the ability to add those declarations in one place, without having to change two different module files every time you need to make a small update.

The next file to change is your app’s markup file. To do that, open your list.component.tns.html file and paste in the following code.

<ListView [items]="items">
  <ng-template let-item="item">
    <FlexboxLayout [class.selected]="item.selected" (tap)="itemTapped(item)">
      <Image [src]="item.image"></Image>
      <Label [text]="item.name"></Label>
    </FlexboxLayout>
  </ng-template>
</ListView>

TIP: Need help learning these NativeScript user interface components? Try NativeScript Playground, and specifically, try out the components pane on the bottom-left-hand side of the screen.

Next, to style these components, paste the following code into your list.component.tns.css file.

FlexboxLayout {
  padding: 5;
  align-items: center;
}
.selected {
  background-color: #C0C0C0;
}
Image {
  height: 80;
  width: 80;
}

TIP: If you’re a fan of SASS, you can use it with NativeScript schematics and share CSS variables such as colors. Check out the instructions here on the NativeScript documentation.

With all this in place, your last step is to import your ListModule in your app.module.tns.ts file, exactly like you did with your app.module.ts file. To do so, replace the contents of your app.component.tns.ts file with the following code.

import { NgModule, NO_ERRORS_SCHEMA } from '@angular/core';
import { NativeScriptModule } from 'nativescript-angular/nativescript.module';

import { AppRoutingModule } from './app.routing';
import { AppComponent } from './app.component';
import { ListModule } from './list/list.module';

@NgModule({
  bootstrap: [
    AppComponent
  ],
  imports: [
    NativeScriptModule,
    AppRoutingModule,
    ListModule
  ],
  declarations: [
    AppComponent
  ],
  providers: [
  ],
  schemas: [
    NO_ERRORS_SCHEMA
  ]
})
export class AppModule { }

And with that, you should have a functioning NativeScript app, right? Actually there’s one last change you need to make, and to show it let’s introduce the concept of helper files.

Using helper files

When taking a code-sharing approach, sometimes you need to completely split your implementations for web and native. Your user interfaces for example always need different implementations, as you need to use DOM nodes for the web, and NativeScript user-interface controls for mobile.

However, there are often times where you can share almost all of your code, but need slightly different implementations for the web and mobile. There’s actually one example of this in your sample app, and it’s in your list.service.ts file.

If you open list.service.ts, you’ll see two different references to localStorage—one in the constructor...

let saved = localStorage.getItem('items');

...and another in the save() method.

localStorage.setItem('items', JSON.stringify(this.saved));

The problem here is localStorage is a browser API. It works great on the web, but it does not exist in NativeScript apps because NativeScript apps do not run in a browser.

You have a few different ways you could handle this. You could create a list.service.tns.ts file, and create a separate implementation of this service that works for your mobile app. However, if you do that you need to duplicate a lot of code that is the same across both platforms, such as the code that calls your backend over HTTP and parses the data.

When you hit these scenarios another option you have is to create helper files. That is, create two files with identical APIs, and put your web implementation of those APIs in one file, and your NativeScript implementation of those APIs in another.

To do this for your service create two new files named list.helper.ts and list.helper.tns.ts. Your new folder structure should now look like this.

. app
└── list
    ├── list.common.ts
    ├── list.component.css
    ├── list.component.html
    ├── list.component.tns.css
    ├── list.component.tns.html
    ├── list.component.ts
    ├── list.helper.tns.ts (new)
    ├── list.helper.ts (new)
    ├── list.module.ts
    ├── list.module.tns.ts
    └── list.service.ts

TIP: In a real-world app you would probably want to move the service and its helper files to its own folder, both to break up the folder structure, and to make the service reusable. For this tutorial though it’s easiest for us to keep everything in one place.

Open your list.helper.ts file and paste in the following code. This is the same localStorage code you had in your service extracted into a helper.

export class ListHelper {
  readItems() {
    let saved = localStorage.getItem('items');
    if (saved) {
      return JSON.parse(saved);
    } else {
      return [];
    }
  }

  writeItems(items) {
    localStorage.setItem('items', JSON.stringify(items));
  }
}

Next, open your list.helper.tns.ts file and paste in the following code. This code follows the same API as the web helper, but instead uses some of NativeScript’s built-in modules to accomplish the same task for your iOS and Android apps.

import { knownFolders, File } from 'tns-core-modules/file-system';

export class ListHelper {
  saveFile: File;

  constructor() {
    this.saveFile = knownFolders.documents().getFile('items.json');
  }

  readItems() {
    const items = this.saveFile.readTextSync();
    return items ? JSON.parse(items) : [];
  }

  writeItems(items) {
    this.saveFile.writeText(JSON.stringify(items));
  }
}

Your last step here is changing your service to utilize these new helpers, which you can do by replacing the code in your list.service.ts file with the code below, which makes use of the new helpers.

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { map } from 'rxjs/operators';

import { ListHelper } from './list.helper';

@Injectable()
export class ListService {
  saved: any[];
  helper: ListHelper;

  constructor(private http: HttpClient) {
    this.helper = new ListHelper();
    this.saved = this.helper.readItems();
  }

  get() {
    return this.http.get('https://rawgit.com/tjvantoll/ShinyDex/master/assets/151.json')
      .pipe(
        map((data: any) => {
          const returnData = [];
          data.results.forEach((item) => {
            item.selected = this.saved.indexOf(item.id) != -1;
            returnData.push(item);
          })
          return returnData;
        })
      );
  }

  toggleSelected(item) {
    if (item.selected) {
      this.saved.splice(this.saved.indexOf(item.id), 1);
    } else {
      this.saved.push(item.id);
    }

    item.selected = !item.selected;
    this.save();
  }

  save() {
    this.helper.writeItems(this.saved);
  }
}

Now that you have all your code in place, go ahead and run your app on iOS or Android using one of the following commands.

npm run ios

npm run android

You should see an app that looks something like this.

Although this app is simple it’s important to remember what you’re seeing here. These are native iOS and Android apps, using native iOS and Android user interface controls. And not only did you build these apps with Angular and TypeScript, you even shared a good chunk the code behind this app with your web app.

NOTE: You can learn more about using helper files to split your code from this article on the NativeScript documentation.

The big picture

In this article we looked at how to build a simple component that shares code across the web and native apps. Although we focused on one component for this article, the approach is flexible enough to build apps of any scale.

Depending on your needs, you might want to create relatively identical apps for both the web and mobile. Or, you might want to create very different apps that share the same language, framework, underlying infrastructure, and service layer.

After all, the power from using NativeScript schematics is not just code sharing—you also gain a ton from using one language and one framework to build for three platforms. Hopefully you’re as excited as me about the awesome things you can build with this technology stack.