DEV Community: Ignacio Le Fluk

Svelte Component Testing with Cypress + Vite

Ignacio Le Fluk — Mon, 08 Aug 2022 00:00:49 +0000

Cypress is a well-known e2e and integration testing framework. But since v7, a Cypress Component Test Runner was introduced, and it can be used to render and test components in isolation. It's still in alpha, so things may change!
In this blog post, we will set up our environment to test Svelte components while using Vite.

Starting a new project

First, we will start by creating a new project with Vite.

npm init vite@latest
// Project name: › cypress-svelte-testing
// Select a framework: › svelte
// Select a variant: › svelte-ts

cd cypress-svelte-testing
npm install

*Note: check Vite's documentation to find out how to start a project with other package managers.

The project is now configured to use Svelte and TypeScript.

To start our server, we need to run the command npm run dev.

We will be testing this application which consists of two components: App and Counter.
App is the shell, or the main component wrapping the counter component: a button that updates its count when clicked.

Installing dependencies

To run our tests, we need to install a few dependencies:
cypress: The testing framework
@cypress/vite-dev-server: Responsible for lanching and restarting the server when files change.
cypress-svelte-unit-test: A package to mount our components in the testing environment. Unfortunately, there's is no support at the moment of writing for our current environment, so we will be using a fork, and then we'll install it from the repo.
@testing-library/cypress: Optional. Adds selectors for our queries.

Let's go ahead and install all of these as dev-dependencies.

npm i --save-dev cypress @cypress/vite-dev-server @testing-library/cypress

npm i --save-dev https://github.com/flakolefluk/cypress-svelte-unit-test

Configuring the test environment

Now, we need to follow we will have to update or create some files to configure our environment. We'll go through each of them.

<root>/cypress.json to let cypress know where to find the component test files.

{
  "componentFolder": "src",
  "testFiles": "**/*spec.{js,jsx,ts,tsx}"
}

<root>/cypress/plugins/index.ts to configure the dev server:

import { startDevServer } from '@cypress/vite-dev-server';
import path from 'path';

module.exports = (on, config) => {
  on('dev-server:start', async (options) => {
    return startDevServer({
      options,
      viteConfig: {
        configFile: path.resolve(__dirname, '..', '..', 'vite.config.js'),
      },
    });
  });

  return config;
};

<root>/cypress/support/commands.js to add the testing library commands

import '@testing-library/cypress/add-commands';

<root>/tsconfig.json to add typescript support for the testing library commands

{
  // ...
  "compilerOptions": {
    // ...
    // add the following and preserve the rest of the config file
    "types": ["cypress", "@testing-library/cypress"]
  },
  // ...
}

<root>/package.json to add a few scripts that will run our tests

{
  // ...
  "scripts": {
// ...
    "cy:open-ct": "cypress open-ct",
    "cy:run-ct": "cypress run-ct"
  },
  // ...
}

Our tests are ready to be written!

In our cypress configuration file, we declared that the tests will live inside the src. This makes it possible to locate our tests next to our components.

Writing tests

We will test both components that were created along with the project.

Create two files, one next to each component:

// <root>/src/App.spec.ts
import App from './App.svelte';
import { mount } from 'cypress-svelte-unit-test';
describe('App', function () {
  it('renders App with correct heading', () => {
    mount(App);
    cy.findByRole('heading', { level: 1, name: /hello typescript/i }).should(
      'exist'
    ).should('be.visible');
  });
});

// <root>/src/Counter.spec.ts
import Counter from './Counter.svelte';
import { mount } from 'cypress-svelte-unit-test';
describe('Counter', function () {
  it('Renders button and updates count when clicked', () => {
    mount(Counter);
    cy.findByRole('button', { name: 'Clicks: 0' }).should('exist');
    cy.findByRole('button', { name: /Click/i }).click();
    cy.findByRole('button', { name: 'Clicks: 1' }).should('exist');
  });
});

I wrote a couple of tests as a start.
First, we check the App component and that it contains a heading with content, we also check that the element is visible.

For our Counter component, we first check that it exists. Then we click it and verify that the text inside it is updated with the expected current count.

In both tests, I'm using the queries provided by the *testing-library * package.

Running our tests

We can run our tests in two ways, with the run-ct and open-ct commands. The first one will tun the tests headlessly by default, while the second one will open the test runner.

Let's try both.

npm run cy:run-ct Your tests will run in your terminal and you'll get a nice overview of them.

npm run cy:open-ct Your tests will open in a browser and you'll be able to go through every step of your tests, which will make debugging a lot easier as you can see what's happening.

Time to write more tests!

Final thoughts

I hope this tutorial will help you set up your environment for working with Vite and Cypress to test your Svelte components. I find that testing with the open-ct command is really useful when writing tests. Most of the configuration shown is applicable to other frameworks too (There are other packages that will mount the components). Check the official documentation for more. You can find the code shown here in this repo.

This Dot Labs is a development consultancy focused on providing staff augmentation, architectural guidance, and consulting to companies.

We help implement and teach modern web best practices with technologies such as React, Angular, Vue, Web Components, GraphQL, Node, and more.

Component Testing in Svelte

Ignacio Le Fluk — Sun, 20 Feb 2022 04:27:45 +0000

Testing helps us trust our application, and it's a safety net for future changes. In this tutorial, we will set up our Svelte project to run tests for our components.

Starting a new project

Let's start by creating a new project:

pnpm dlx create-vite
// Project name: › testing-svelte
// Select a framework: › svelte
// Select a variant: › svelte-ts

cd testing-svelte
pnpm install

There are other ways of creating a Svelte project, but I prefer using Vite. One of the reasons that I prefer using Vite is that SvelteKit will use it as well. I'm also a big fan of pnpm, but you can use your preferred package manager. Make sure you follow Vite's docs on starting a new project using npm or yarn.

Installing required dependencies

Jest: I'll be using this framework for testing. It's the one that I know best, and feel more comfortable with. Because I'm using TypeScript, I need to install its type definitions too.
ts-jest: A transformer for handling TypeScript files.
svelte-jester: precompiles Svelte components before tests.
Testing Library: Doesn't matter what framework I'm using, I will look for an implementation of this popular library.

pnpm install --save-dev jest @types/jest @testing-library/svelte svelte-jester ts-jest

Configuring tests

Now that our dependencies are installed, we need to configure jest to prepare the tests and run them.

A few steps are required:

Convert *.ts files
Complile *.svelte files
Run the tests

Create a configuration file at the root of the project:

// jest.config.js
export default {
  transform: {
    '^.+\\.ts$': 'ts-jest',
    '^.+\\.svelte$': [
      'svelte-jester',
      {
        preprocess: true,
      },
    ],
  },
  moduleFileExtensions: ['js', 'ts', 'svelte'],
};

Jest will now use ts-jest for compiling *.ts files, and svelte-jester for *.svelte files.

Creating a new test

Let's test the Counter component created when we started the project, but first, I'll check what our component does.

<script lang="ts">
  let count: number = 0;
  const increment = () => {
    count += 1;
  };
</script>

<button on:click={increment}>
  Clicks: {count}
</button>

<style>
  button {
    font-family: inherit;
    font-size: inherit;
    padding: 1em 2em;
    color: #ff3e00;
    background-color: rgba(255, 62, 0, 0.1);
    border-radius: 2em;
    border: 2px solid rgba(255, 62, 0, 0);
    outline: none;
    width: 200px;
    font-variant-numeric: tabular-nums;
    cursor: pointer;
  }

  button:focus {
    border: 2px solid #ff3e00;
  }

  button:active {
    background-color: rgba(255, 62, 0, 0.2);
  }
</style>

This is a very small component where a button when clicked, updates a count, and that count is reflected in the button text.
So, that's exactly what we'll be testing.

I'll create a new file ./lib/__tests__/Counter.spec.ts

/**
 * @jest-environment jsdom
 */

import { render, fireEvent } from '@testing-library/svelte';
import Counter from '../Counter.svelte';

describe('Counter', () => {
  it('it changes count when button is clicked', async () => {
    const { getByText } = render(Counter);
    const button = getByText(/Clicks:/);
    expect(button.innerHTML).toBe('Clicks: 0');
    await fireEvent.click(button);
    expect(button.innerHTML).toBe('Clicks: 1');
  });
});

We are using render and fireEvent from testing-library. Be mindful that fireEvent returns a Promise and we need to await for it to be fulfilled.
I'm using the getByText query, to get the button being clicked.
The comment at the top, informs jest that we need to use jsdom as the environment. This will make things like document available, otherwise, render will not be able to mount the component. This can be set up globally in the configuration file.

What if we wanted, to test the increment method in our component?
If it's not an exported function, I'd suggest testing it through the rendered component itself. Otherwise, the best option is to extract that function to another file, and import it into the component.

Let's see how that works.

// lib/increment.ts
export function increment (val: number) {
    val += 1;
    return val
  };

<!-- lib/Counter.svelte -->
<script lang="ts">
  import { increment } from './increment';
  let count: number = 0;
</script>

<button on:click={() => (count = increment(count))}>
  Clicks: {count}
</button>
<!-- ... -->

Our previous tests will still work, and we can add a test for our function.

// lib/__tests__/increment.spec.ts

import { increment } from '../increment';

describe('increment', () => {
  it('it returns value+1 to given value when called', async () => {
    expect(increment(0)).toBe(1);
    expect(increment(-1)).toBe(0);
    expect(increment(1.2)).toBe(2.2);
  });
});

In this test, there's no need to use jsdom as the test environment. We are just testing the function.

If our method was exported, we can then test it by accessing it directly.

<!-- lib/Counter.svelte -->
<script lang="ts">
  let count: number = 0;
  export const increment = () => {
    count += 1;
  };
</script>

<button on:click={increment}>
  Clicks: {count}
</button>
<!-- ... -->

// lib/__tests__/Counter.spec.ts

describe('Counter Component', () => {
 // ... other tests

  describe('increment', () => {
    it('it exports a method', async () => {
      const { component } = render(Counter);
      expect(component.increment).toBeDefined();
    });

    it('it exports a method', async () => {
      const { getByText, component } = render(Counter);
      const button = getByText(/Clicks:/);
      expect(button.innerHTML).toBe('Clicks: 0');
      await component.increment()
      expect(button.innerHTML).toBe('Clicks: 1');
    });
  });
});

When the method is exported, you can access it directly from the returned component property of the render function.

NOTE: I don't recommend exporting methods from the component for simplicity if they were not meant to be exported. This will make them available from the outside, and callable from other components.

Events

If your component dispatches an event, you can test it using the component property returned by render.

To dispatch an event, we need to import and call createEventDispatcher, and then call the returning funtion, giving it an event name and an optional value.

<!-- lib/Counter.svelte -->
<script lang="ts">
  import { createEventDispatcher } from 'svelte';
  const dispatch = createEventDispatcher();

  let count: number = 0;
  export const increment = () => {
    count += 1;
    dispatch('countChanged', count);
  };
</script>

<button on:click={increment}>
  Clicks: {count}
</button>
<!-- ... -->

// lib/__tests__/Counter.spec.ts
// ...

  it('it emits an event', async () => {
    const { getByText, component } = render(Counter);
    const button = getByText(/Clicks:/);
    let mockEvent = jest.fn();
    component.$on('countChanged', function (event) {
      mockEvent(event.detail);
    });
    await fireEvent.click(button);

    // Some examples on what to test
    expect(mockEvent).toHaveBeenCalled(); // to check if it's been called
    expect(mockEvent).toHaveBeenCalledTimes(1); // to check how any times it's been called
    expect(mockEvent).toHaveBeenLastCalledWith(1); // to check the content of the event
    await fireEvent.click(button);
    expect(mockEvent).toHaveBeenCalledTimes(2);
    expect(mockEvent).toHaveBeenLastCalledWith(2);
  });

//...

For this example, I updated the component to emit an event: countChanged. Every time the button is clicked, the event will emit the new count.
In the test, I'm using getByText to select the button to click, and component.

Then, I'm using component.$on(eventName), and mocking the callback function to test the emitted value (event.detail).

Props

You can set initial props values, and modifying them using the client-side component API.

Let's update our component to receive the initial count value.

<!-- lib/Counter.svelte -->
<script lang="ts">
// ...
  export let count: number = 0;
// ...
</script>

<!-- ... -->

Converting count to an input value requires exporting the variable declaration.

Then we can test:

default values
initial values
updating values

// lib/__tests__/Counter.ts
// ...
describe('count', () => {
    it('defaults to 0', async () => {
      const { getByText } = render(Counter);
      const button = getByText(/Clicks:/);
      expect(button.innerHTML).toBe('Clicks: 0');
    });

    it('can have an initial value', async () => {
      const { getByText } = render(Counter, {props: {count: 33}});
      const button = getByText(/Clicks:/);
      expect(button.innerHTML).toBe('Clicks: 33');
    });

    it('can be updated', async () => {
      const { getByText, component } = render(Counter);
      const button = getByText(/Clicks:/);
      expect(button.innerHTML).toBe('Clicks: 0');
      await component.$set({count: 41})
      expect(button.innerHTML).toBe('Clicks: 41');
    });
});
// ...

We are using the second argument of the render method to pass initial values to count, and we are testing it through the rendered button

To update the value, we are calling the $set method on component, which will update the rendered value on the next tick. That's why we need to await it.

Wrapping up

Testing components using Jest and Testing Library can help you avoid errors when developing, and also can make you more confident when applying changes to an existing codebase. I hope this blog post is a step forward to better testing.

You can find these examples in this repo

This Dot Labs is a development consultancy focused on providing staff augmentation, architectural guidance, and consulting to companies.

We help implement and teach modern web best practices with technologies such as React, Angular, Vue, Web Components, GraphQL, Node, and more.

Animations in Svelte

Ignacio Le Fluk — Sun, 20 Feb 2022 04:27:26 +0000

Animations are more present than ever in our websites and applications. They can make them look and feel different if done right, engaging your users.
In this post, we'll learn how animations can be used in Svelte, and how you can extend those that are shipped with the library.

Modules

Svelte ships a series of modules that will help us while creating animations.
We'll explore each of these to understand what they do.

animate
easing
motion
transition

svelte/easing

This package contains a series of functions with equations to produce different easing curves
Available curves are:

back
bounce
circ
cubic
elastic
expo
quad
quart
quint
sine

But you can create your custom function as long as it's a function that will accept 1 parameter varying from 0 to 1 (1 represents the total duration of the animation) and returns another value, also ranging from 0 to 1.

svelte/motion

Two functions are exported in this package: tweened and spring.

Both of them will return a reactive value, interpolating in-between values given a set of parameters.

Note that these functions do not necessarily animate anything visually, but rather, create a ramp between values. These values can then be displayed or assigned to something else, like CSS properties.

Both functions can interpolate numbers, dates, arrays, and objects. You can also provide a different function for interpolating values.

tweened

Let's initialize a new Svelte app to see how it works.

npm init vite

✔ Project name: · svelte-animations
✔ Select a framework: · svelte
✔ Select a variant: · svelte-ts

cd svelte-web-components
pnpm install //use the package manager you prefer
pnpm run dev

// remove default Counter component
rm src/lib/Counter.svelte

Clear the App.svelte component to contain only what we need now.

<script>
    // add imports here
</script>

<main>
</main>

<style>
  :root {
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen,
      Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
  }

  main {
    text-align: center;
    padding: 1em;
    margin: 0 auto;
  }

  :global(main > * + *)  {
    margin-top: 24px;
  }
</style>

I'll create a new component named Tasks.svelte inside the lib folder.

<script lang="ts">
  import { tweened } from 'svelte/motion';
  export let tasks: { id; title; date }[] = [];

  let selected;
  tasks = tasks.sort((a, b) => {
    if (a.date > b.date) {
      return 1;
    } else if (a.date === b.date) {
      return 0;
    } else {
      return -1;
    }
  });

  function pad(num) {
    if (num < 10) {
      return `0${num}`;
    }
    return num;
  }

  function getDate(date) {
    return date
      ? `${date.getFullYear()}/${pad(date.getMonth() + 1)}/${pad(
          date.getDate(),
        )}`
      : '';
  }

  function getTime(date) {
    return date ? `${pad(date.getHours())}:${pad(date.getMinutes())}` : '';
  }

  let now = new Date();
  let date = tweened(now, { duration: 500 });

  function selectTask(task) {
    selected = task.id;
    date.set(task.date);
  }
</script>

<div class="task-view">
  <div class="task-list">
    <h2>Next tasks</h2>
    <ul>
      {#each tasks as task}
        <li
          class={selected === task.id ? 'selected' : ''}
          on:click={() => selectTask(task)}
        >
          {task.title}
        </li>
      {/each}
    </ul>
  </div>
  <div class="task-details">
    <h2>When?</h2>
    {#if selected}
      <p>{getDate($date)}</p>
      <p>{getTime($date)}</p>
    {/if}
  </div>
</div>

<style>
  .task-view {
    display: flex;
    flex-direction: row;
    justify-content: space-between;
    width: 300px;
    border: 2px solid #4f4f4f;
    border-radius: 8px;
    padding: 16px;
  }
  li {
    padding: 4px 8px;
  }
  li.selected {
    background-color: lightcyan;
  }
  li:hover {
    background-color: lightgray;
  }
</style>

The component will receive a list of tasks with a title and date, and then we'll create a transition between these dates when clicking any of them. (Look at how we auto-subscribe to the reactive value, prepending the variable name with $)

Let's update the App to use this component.

<script lang="ts">
  import Tasks from './lib/Tasks.svelte';

  let tasks = [
    { id: 1, title: 'Meeting', date: new Date('2021-12-17T03:24:00') },
    { id: 2, title: 'Gym', date: new Date('2021-08-22T09:12:00') },
    { id: 3, title: 'Movie', date: new Date('2021-09-01T22:07:00') },
  ];
</script>

<main>
  <Tasks {tasks} />
</main>
<!-- ... -->

And the result looks like this:

In this example we are animating the value, but we can also apply these changes to CSS properties.

Let's create another example that achieves this. (Tweened.svelte).

<script>
  import { tweened } from 'svelte/motion';
  import { cubicOut } from 'svelte/easing';

  const toColor = tweened([255, 0, 0], {
    duration: 2000,
    easing: cubicOut,
  });

  let loop = () =>
    toColor
      .set([255, 0, 0])
      .then(() => toColor.set([0, 255, 0]))
      .then(() => toColor.set([0, 0, 255]))
      .then(() => loop());
  loop();
</script>

<div style={'background-color:rgb(' + $toColor.join(',') + ')'} />

<style>
  div {
    display: block;
    width: 100px;
    height: 100px;
  }
</style>

Here, we created a single div, and use tweened to interpolate values of an array.

When we set the value using the set function, it will return a promise that resolves when the final value is reached (for our purposes, the animation has ended). Then, we trigger a new value using set again. We can see in action how we can interpolate array values.

We must remember to update our application

<script lang="ts">
// ...
  import Tweened from './lib/Tweened.svelte';
// ...
</script>

<main>
  <!-- ... -->
  <Tweened />
</main>

The possible parameters for tweened are: delay (time before starting), duration (in milliseconds), easing (one of the easing functions shown before), interpolate (a (from, to) => t => value) function

Spring

Spring works differently to transition a variable from one value to another. We can set three parameters: stiffness, damping, which will set how the spring behaves while settling in the final value, and precision, which will determine when the value is considered settled.

Let's create a new component named Spring.svelte

<script>
    import { spring } from 'svelte/motion';

    const number = spring(0,{
    stiffness: 0.1,
    damping: 0.08
});

function changeValueTo(newValue) {
    number.set(newValue)
}

function resetValue() {
    number.set(0, {hard:true})
}

</script>

<div>
    <span>{$number.toFixed(1)}</span>
    <button on:click={() => changeValueTo(10)}>To 10</button>
    <button on:click={() => changeValueTo(100)}>To 100</button>
    <button on:click={() => changeValueTo(1000)}>To 1000</button>
    <button  on:click={() => resetValue()}>Reset</button>
</div>

<style>
    div {
        display: flex;
        flex-direction:column;
        max-width:300px;
    }
</style>

Our component has a number reactive value that will bounce when changed until finally settling in the desired result. The larger the distance to the target value, the more it will bounce.

We need to update our app to import the component.

<script lang="ts">
// ...
  import Spring from './lib/Spring.svelte';
// ...
</script>

<main>
  <!-- ... -->
  <Spring />
</main>

This is what the final result looks like.

svelte/transition

A transition is a function with the following signature:

(node: HTMLElement, params: any) => {
    delay?: number,
    duration?: number,
    easing?: (t: number) => number,
    css?: (t: number, u: number) => string,
    tick?: (t: number, u: number) => void
}

The svelte/transition module includes a series of functions that will let us animate our DOM: blur, draw, fade, fly, scale, slide and crossfade(this last function returns two transition functions)

They are used with the transition, in, or out directives.
Transition is executed when the element enters or leaves the DOM. Four events are available with this directive introstart, introend, outrostart, outroend they are triggered whenever the initial or final animations start and end.

The in and out directives work like transition, but they only act when either the element is added or removed.

Create a new component named Transition.svelte.

<script lang="ts">
  import { onDestroy, onMount } from 'svelte';
  import {
    blur,
    crossfade,
    draw,
    fade,
    fly,
    scale,
    slide,
  } from 'svelte/transition';

  let show = false;
  let interval;

  let [from, to] = crossfade({
    fallback: () => {
      return { css: (t, u) => 'color:red' };
    },
  });

  onMount(() => {
    interval = setInterval(() => {
      show = !show;
    }, 2000);
  })

  onDestroy(() => {
    if (interval) {
      clearInterval(interval);
    }  
  });
</script>

<div class="playground">
  <div class="transition-item">
    <svg
      fill="#ffffff"
      width="32"
      height="32"
      viewBox="0 0 16 16"
      xmlns="http://www.w3.org/2000/svg"
    >
      {#if show}
        <path
          in:draw={{ duration: 1500 }}
          d="M1.414213562373095 0 16 14.585786437626904 L14.585786437626904 16 L0 1.414213562373095"
        />
        <path
          in:draw={{ duration: 1500 }}
          d="M14.585786437626904 0 L16 1.414213562373095 L1.414213562373095 16 L0 14.585786437626904"
        />
      {/if}
    </svg>
  </div>
  <div class="transition-item teleport">
    <div>
      {#if show}
        <span in:from={{ key: 'a' }} out:to={{ key: 'a' }}>cross...</span>
      {/if}
    </div>
    <div>
      {#if !show}
        <span in:from={{ key: 'a' }} out:to={{ key: 'a' }}>...fade</span>
      {/if}
    </div>
  </div>

  {#if show}
    <div class="transition-item" transition:blur>
      <span>Blur</span>
    </div>
    <div class="transition-item" transition:fade>
      <span>Fade</span>
    </div>
    <div class="transition-item" transition:fly={{ x: 30 }}>
      <span>Fly</span>
    </div>
    <div class="transition-item" transition:scale={{ start: 10 }}>
      <span>Scale</span>
    </div>
    <div class="transition-item" transition:slide>
      <span>Slide</span>
    </div>
  {/if}
</div>

<style>
  .teleport {
    display: flex;
    flex-direction: row;
    justify-content: center;
    width: 200px;
    margin-left:auto;
    margin-right:auto;
    border: 2px solid #4f4f4f;
    border-radius: 8px;
    padding: 16px;

  }
  .teleport > div {
      width: 100px;
    }

  svg {
    height: 128px;
    width: 128px;
  }

  path {
    stroke: black;
  }

  .transition-item + .transition-item {
    margin-top: 40px;
  }
</style>

I've added all of the provided animations to this example, so you can play around with them.

Custom transitions

We can create custom transitions by creating a function that accepts an HTML element, and a configuration object, and returns an object with the required properties.

We'll create a new function called skew.

export function skew(node: HTMLElement, {delay = 0, duration = 1000, easing = cubicInOut, deg = 45} = {}) {
        const style = getComputedStyle(node);
        const target_opacity = +style.opacity;
        const transform = style.transform === 'none' ? '' : style.transform;
        return {
            delay,
            duration,
            easing,
            css: (_t, u) => `
                transform: ${transform} skew(${deg * u}deg);
                opacity: ${target_opacity * _t}
            `
        };
}

delay, duration, and easing are pretty standard to all shipped functions, so we'll keep them the same for ease of use. The magic happens in our css property. Based on our parameters, we will add the skew transform. u is nothing but 1-_t, so in this case, we will start from deg (skew is applied) to 0 (no skew) when the element is shown.
The opposite will happen when removed.

Let's test it by creating a new component. (Skew.svelte)

<script lang="ts">
  import { onDestroy, onMount } from 'svelte';
  import { skew } from './skew';

  export let skewOptions = {};

  let show = false;
  let interval;

  onMount(() => {
    interval = setInterval(() => {
      show = !show;
    }, 2000);
  });

  onDestroy(() => {
    if (interval) {
      clearInterval(interval);
    }
  });
</script>

<div class="playground">
  {#if show}
    <div class="transition-item" transition:skew={skewOptions}>
      <span>Skew</span>
    </div>
  {/if}
</div>

svelte/animate

This package exports a single function: flip.
Animations are to be used with the animate directive.

Note that there is a requirement to use this directive.
The element that uses the animate directive must be the immediate child of a keyed each block.

Animations are triggered when the elements of an each block are reordered.

The signature of an animation is:

(node: HTMLElement, { from: DOMRect, to: DOMRect } , params: any) => {
    delay?: number,
    duration?: number,
    easing?: (t: number) => number,
    css?: (t: number, u: number) => string,
    tick?: (t: number, u: number) => void
}

As you can see the signature is very similar to those of the transitions. We'll make use of this similarity later.

Create a new component to test what flip and the animate directive do.

<!-- Flip.svelte -->

<script lang="ts">
  import { flip } from 'svelte/animate';
  let things = [
    { id: 1, name: 'foo', ready: true },
    { id: 2, name: 'bar', ready: false },
    { id: 3, name: 'baz', ready: true },
    { id: 4, name: 'fizz', ready: false },
  ];
  let sortBy = { field: 'id', order: 'DESC' };

  let sortedThings = things;

  function sortById() {
    if (
      sortBy.field !== 'id' ||
      (sortBy.field === 'id' && sortBy.order === 'DESC')
    ) {
      sortedThings = things.sort((a, b) => {
        if (a.id > b.id) {
          return 1;
        } else if (a.id < b.id) {
          return -1;
        }
        return 0;
      });
      sortBy = { field: 'id', order: 'ASC' };
    } else {
      sortedThings = things.sort((a, b) => {
        if (a.id > b.id) {
          return -1;
        } else if (a.id < b.id) {
          return 1;
        }
        return 0;
      });
      sortBy = { field: 'id', order: 'DESC' };
    }
  }
  function sortByName() {
    if (
      sortBy.field !== 'name' ||
      (sortBy.field === 'name' && sortBy.order === 'DESC')
    ) {
      sortedThings = things.sort((a, b) => {
        if (a.name > b.name) {
          return 1;
        } else if (a.name < b.name) {
          return -1;
        }
        return 0;
      });
      sortBy = { field: 'name', order: 'ASC' };
    } else {
      sortedThings = things.sort((a, b) => {
        if (a.name > b.name) {
          return -1;
        } else if (a.name < b.name) {
          return 1;
        }
        return 0;
      });
      sortBy = { field: 'name', order: 'DESC' };
    }
  }
  function sortByReadyState() {
    if (
      sortBy.field !== 'ready' ||
      (sortBy.field === 'ready' && sortBy.order === 'DESC')
    ) {
      sortedThings = [
        ...sortedThings.filter((x) => x.ready),
        ...sortedThings.filter((x) => !x.ready),
      ];
      sortBy = { field: 'ready', order: 'ASC' };
    } else {
      sortedThings = [
        ...sortedThings.filter((x) => !x.ready),
        ...sortedThings.filter((x) => x.ready),
      ];
      sortBy = { field: 'ready', order: 'DESC' };
    }
  }
</script>

<div class="container">
  <table>
    <tr>
      <th on:click={sortById}>id</th>
      <th on:click={sortByName}>name</th>
      <th on:click={sortByReadyState}>ready</th>
    </tr>
    {#each sortedThings as thing (thing.id)}
      <tr animate:flip>
        <td>{thing.id}</td>
        <td>
          {thing.name}
        </td>
        <td><input type="checkbox" bind:checked={thing.ready} /></td>
      </tr>
    {/each}
  </table>
</div>

<style>
  td {
    width: 100px;
  }
  .container {
    width: 100vw;
    display: flex;
    flex-direction: row;
  }
  table,
  tr,
  td,
  th {
    border: 1px solid gray;
    border-collapse: collapse;
  }
  th {
    cursor: pointer;
  }
</style>

We created a table with 4 rows, and the ability to order rows by different properties.

The elements are inside a keyed each block (remember this is a requirement).
One of the cool things about the animate directive is that only the items that change will be animated. The rest will remain like they were.

The result looks like this.

extending and reusing animations with transitions

Because transitions and animations are so similar, we can use transitions to extend flip or create new animations.

animations from transitions

If we look at both types of functions, we can see that we are able to create a wrapper function to convert our transition into an animation.

export function toAnimation<T>(
  fn: (node: HTMLElement, params) => T,
): (node: HTMLElement, { from, to }, params) => T {
  return (node, _animations, params = {}) => {
    return fn(node, params);
  };
}

Then, we can convert one of our transitions, and apply it with the animate directive.

<!--AnimationFromTransition.svelte -->
<script>
  import { fade } from 'svelte/transition';
  import { toAnimation } from './toAnimation';

  let fadeAnimation = toAnimation(fade);

 // ... same as Flip.svelte
</script>

<div class="container">
  <table>
    <tr>
      <th on:click={sortById}>id</th>
      <th on:click={sortByName}>name</th>
      <th on:click={sortByReadyState}>ready</th>
    </tr>
    {#each sortedThings as thing (thing.id)}
      <tr animate:fadeAnimation={{ duration: 400 }}>
        <td>{thing.id}</td>
        <td>
          {thing.name}
        </td>
        <td><input type="checkbox" bind:checked={thing.ready} /></td>
      </tr>
    {/each}
  </table>
</div>

<style>
  /* same as Flip.svelte*/
</style>

Now, instead of moving, reordered elements fade in/out.

Extending flip

We can also extend the flip animation with transitions. I'll create a wrapper function again.

// extendFlip.ts

import { flip } from 'svelte/animate';
export function extendFlip(fn) {
  return (node, animations, params = {}) => {
    let flipRes = flip(node, animations, params);
    let transitionRes = fn(node, params);

    let getTransform = (str) => {
      let results = str.match(/transform: (.*);/);
      if (results && results.length) {
        return results[results.length - 1];
      }
      return '';
    };

    let mergeTransform = (css1, css2) => {
      return `transform: ${getTransform(css1)} ${getTransform(css2)};`;
    };

    return {
      ...flipRes,
      css: (t, u) =>
        `${transitionRes.css(t, u)}; ${mergeTransform(
          flipRes.css(t, u),
          transitionRes.css(t, u),
        )};`,
    };
  };
}

Our function will get the transition function, and merge the transform property it returns with the one from flip.

Now, let's look at a slightly modified version of the previous component:

<script>
  import { scale, blur } from 'svelte/transition';
  import { extendFlip } from './extendFlip';

  let flipAndBlur = extendFlip(blur);
  let flipAndScale = extendFlip(blur);

  let things = [
    { id: 1, name: 'foo', ready: true },
    { id: 2, name: 'bar', ready: false },
    { id: 3, name: 'baz', ready: true },
    { id: 4, name: 'fizz', ready: false },
  ];

  let sortBy = { field: 'id', order: 'DESC' };

  let sortedThings = things;

  function sortById() {
    if (
      sortBy.field !== 'id' ||
      (sortBy.field === 'id' && sortBy.order === 'DESC')
    ) {
      sortedThings = things.sort((a, b) => {
        if (a.id > b.id) {
          return 1;
        } else if (a.id < b.id) {
          return -1;
        }
        return 0;
      });
      sortBy = { field: 'id', order: 'ASC' };
    } else {
      sortedThings = things.sort((a, b) => {
        if (a.id > b.id) {
          return -1;
        } else if (a.id < b.id) {
          return 1;
        }
        return 0;
      });
      sortBy = { field: 'id', order: 'DESC' };
    }
  }
  function sortByName() {
    if (
      sortBy.field !== 'name' ||
      (sortBy.field === 'name' && sortBy.order === 'DESC')
    ) {
      sortedThings = things.sort((a, b) => {
        if (a.name > b.name) {
          return 1;
        } else if (a.name < b.name) {
          return -1;
        }
        return 0;
      });
      sortBy = { field: 'name', order: 'ASC' };
    } else {
      sortedThings = things.sort((a, b) => {
        if (a.name > b.name) {
          return -1;
        } else if (a.name < b.name) {
          return 1;
        }
        return 0;
      });
      sortBy = { field: 'name', order: 'DESC' };
    }
  }
  function sortByReadyState() {
    if (
      sortBy.field !== 'ready' ||
      (sortBy.field === 'ready' && sortBy.order === 'DESC')
    ) {
      sortedThings = [
        ...sortedThings.filter((x) => x.ready),
        ...sortedThings.filter((x) => !x.ready),
      ];
      sortBy = { field: 'ready', order: 'ASC' };
    } else {
      sortedThings = [
        ...sortedThings.filter((x) => !x.ready),
        ...sortedThings.filter((x) => x.ready),
      ];
      sortBy = { field: 'ready', order: 'DESC' };
    }
  }
</script>

<div class="container">
  <table>
    <tr>
      <th on:click={sortById}>id</th>
      <th on:click={sortByName}>name</th>
      <th on:click={sortByReadyState}>ready</th>
    </tr>
    {#each sortedThings as thing (thing.id)}
      <tr animate:flipAndBlur>
        <td>{thing.id}</td>
        <td>
          {thing.name}
        </td>
        <td><input type="checkbox" bind:checked={thing.ready} /></td>
      </tr>
    {/each}
  </table>
</div>

<style>
  td {
    width: 100px;
  }
  .container {
    width: 100vw;
    display: flex;
    flex-direction: row;
  }
  table,
  tr,
  td,
  th {
    border: 1px solid gray;
    border-collapse: collapse;
  }
  th {
    cursor: pointer;
  }
</style>

And the results:

Blur + flip

Scale + flip

Final words

Svelte did a great job making animations and transitions easy with their API. The provided functions work great in many scenarios.

I hope this blog post invites you to explore the API, extend what's already there, and share it with other users.
These examples are available in this repo.

This Dot Labs is a modern web consultancy focused on helping companies realize their digital transformation efforts. For expert architectural guidance, training, or consulting in React, Angular, Vue, Web Components, GraphQL, Node, Bazel, or Polymer, visit thisdotlabs.com.

This Dot Media is focused on creating an inclusive and educational web for all. We keep you up to date with advancements in the modern web through events, podcasts, and free content. To learn, visit thisdot.co.

Web Components with Svelte

Ignacio Le Fluk — Fri, 14 Jan 2022 21:11:53 +0000

Svelte is a great framework for building applications, but did you know you can create custom elements and web components with it?

In this post, we'll learn how to create a Svelte component, export it as a custom element, and use it. We'll also learn about limitations when doing it.

Developing

Let's start a new project to build our components.

npm init vite

✔ Project name: · svelte-web-components
✔ Select a framework: · svelte
✔ Select a variant: · svelte-ts

cd svelte-web-components
pnpm install //use the package manager you prefer
pnpm run dev

For this example, we will not be building a Svelte application, but we will need at least a demo page to test all our web components.

We can delete the src/App.svelte file and modify the file located at main.ts to export the files in our library folder, instead of mounting our application.

// src/main.ts
export * from './lib/Counter.svelte'

Then, we need to give a tag to our web component. To achieve this, we need to add a special Svelte element to our component.

<script lang="ts">
  let count: number = 0
  const increment = () => {
    count += 1
  }
</script>

<!--Add this line to your web component-->
<svelte:options tag="my-counter" />

<button on:click={increment}>
  Clicks: {count}
</button>

<style>
  button {
    font-family: inherit;
    font-size: inherit;
    padding: 1em 2em;
    color: #ff3e00;
    background-color: rgba(255, 62, 0, 0.1);
    border-radius: 2em;
    border: 2px solid rgba(255, 62, 0, 0);
    outline: none;
    width: 200px;
    font-variant-numeric: tabular-nums;
    cursor: pointer;
  }

  button:focus {
    border: 2px solid #ff3e00;
  }

  button:active {
    background-color: rgba(255, 62, 0, 0.2);
  }
</style>

The assigned tag is the one that will be used later as a regular HTML element.
For this component: <my-counter></my-counter>

Note: You can also set tag={null} and let the consumer define the tag.

// ...
customElements.define('my-counter', Counter);

It's time to update our demo page to use the web component that will be generated.

<!-- index.html -->

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" href="/favicon.ico" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Svelte + TS + Vite App</title>
  </head>
  <body>
    <my-counter></my-counter>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

I removed the <div id="app"> because we will not be using it. Then, I added our custom element tag to the body of the site.

Finally, we need to tell the compiler that we want to compile our Svelte components as custom elements.

Go to vite.config.js and update it like this:

import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    svelte({
      compilerOptions: {
        customElement: true,
      },
    }),
  ],
});

Let's run our application (pnpm run dev). You should be able to see our web component in action.

It works!

Now, let's create a second web component.

I'll add a clock that will display the current time.

<!-- lib/Clock.svelte -->
<svelte:options tag="my-clock" />

<script lang="ts">
  import { onMount, onDestroy } from 'svelte';
  let date = new Date().toLocaleTimeString();
  let interval;

  onMount(() => {
    interval = setInterval(() => {
      date = new Date().toLocaleTimeString()
    }, 1000);
  });

  onDestroy(() => {
    clearInterval(interval);
  });
</script>

<span>{date|| '' }</span>

<style>
  span {
    font-family: inherit;
    font-size: inherit;
    padding: 1em 2em;
    color: #ff3e00;
    background-color: rgba(255, 62, 0, 0.1);
    border-radius: 2em;
    border: 2px solid rgba(255, 62, 0, 0);
    outline: none;
    width: 200px;
    font-variant-numeric: tabular-nums;
    cursor: pointer;
  }

  span:active {
    background-color: rgba(255, 62, 0, 0.2);
  }
</style>

We should not forget to export it in our main.ts file.

export * from './lib/Counter.svelte'
export * from './lib/Clock.svelte'

And finally, use it in our index.html file.

<!DOCTYPE html>
<html lang="en">
<!-- ... -->
  <body>
    <my-counter></my-counter>
    <my-clock></my-clock>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

Let's run our application, and see the result.

Building

We can keep adding as many web components as we want, but let's inspect our build output.

pnpm run build

vite v2.4.3 building for production...
✓ 6 modules transformed.
dist/index.html                  0.46kb
dist/assets/index.fdfcd12f.js    1.99kb / brotli: 0.67kb
dist/assets/vendor.4be80997.js   5.67kb / brotli: 2.13kb

Our components are bundled together (index.*.js), and the common code is in vendor.*.js. This might be a bit unfortunate if you want to distribute this as a library.

So let's analyze our options:

Bundle our library

If we want to create a single file for our output, we can use the lib option in our vite config.

Let's create a new config file vite.lib.config.js

import { defineConfig } from 'vite'
import { svelte } from '@sveltejs/vite-plugin-svelte'

// https://vitejs.dev/config/
export default defineConfig({
  build:{
    lib:{
      entry: './src/main.ts',
      name: 'MyLibrary',
    }
  },
  plugins: [svelte({
    compilerOptions:{
      customElement: true
    }
  })]
})

Now, we need to run our build process with the right config file.

pnpm run build -- -c=vite.lib.config.js

vite v2.4.3 building for production...
✓ 5 modules transformed.
dist/svelte-web-components.es.js   7.37kb / brotli: 2.60kb
dist/svelte-web-components.umd.js   7.46kb / brotli: 2.64kb

By default, the build.lib options will bundle your library in two formats: es and umd. You can configure it by adding the formats property to the lib settings. Available options are: 'es' | 'cjs' | 'umd' | 'iife'

Everything split

A third option would be to build everything as an independent web component, and a shared code file.

Let's create a different config file for this vite.split.config.js.

import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';

// https://vitejs.dev/config/
export default defineConfig({
  build:{
    rollupOptions: {
      input: ['./src/lib/Counter.svelte', './src/lib/Clock.svelte'],
    }
  },
  plugins: [
    svelte({
      compilerOptions: {
        customElement: true,
      },
    })
  ]
});

The output of this build would look like this:

pnpm run build -- -c=vite.split.config.js

vite v2.4.3 building for production...
✓ 4 modules transformed.
dist/assets/Counter.be2b21b7.js   1.03kb / brotli: 0.52kb
dist/assets/Clock.ca5b7224.js     1.09kb / brotli: 0.53kb
dist/assets/vendor.4be80997.js    5.67kb / brotli: 2.13kb

As you can see, we now have our counter and clock as independent chunks, and both depend on vendor.*.js

You can be specific on how many chunks you want, and what to bundle together or not.

Working with regular Svelte components and custom elements in the same project

When a project is set up to compile to web components, it will try to compile every .svelte file, including your App.svelte file, which may not be what you want.

Let's create a new project, and set it up to work with Svelte components along with other components that will be compiled into custom elements.

npm init vite

✔ Project name: · svelte-web-components-mix
✔ Select a framework: · svelte
✔ Select a variant: · svelte-ts

cd svelte-web-components
pnpm install
pnpm run dev

I will copy the Clock.svelte file from the previous project, and leave the Counter as it is.

We have a problem now. We cannot compile the clock as a custom element, and if we try to do it by modifying the config, the compiler will complain that our App and Counter do not have tags to be compiled.

Luckily, we can have different settings for different files.

// vite.config.js

import { defineConfig } from 'vite'
import { svelte } from '@sveltejs/vite-plugin-svelte'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    svelte({
      exclude: ['./src/lib/Clock.svelte']
    }),
    svelte({
      exclude: ['./src/App.svelte', './src/lib/Counter.svelte'],
      compilerOptions: {
        customElement: true,
      }
    })
  ]
})

As you can see, we set up the Svelte plugin twice, and exclude the files that we need to.

Finally, we will update our App.svelte file to include our Clock custom element, and use it.

<!-- App.svelte -->
<script lang="ts">
  import Counter from './lib/Counter.svelte'
  import './lib/Clock.svelte'
</script>

<main>
  <Counter />
  <my-clock></my-clock>
</main>

If we run our application now, and inspect the document, we will confirm that we are using a web component for the clock along the compiled counter.

Things to consider when building custom elements

There are some limitations/features of custom elements that work differently when working with web components

To prevent props from being accessed from the DOM, add accessors={false} to the svelte:options element
Use a regular CustomEvent instead of the usual createEventDispatcher method from Svelte when emitting from a web component. Add composed:true to cross the Shadow DOM boundaries

<script>
function onClick(e) {
    e.target.dispatchEvent(new CustomEvent('message', {detail:{text:'Hello'}, composed:true}))
}
</script>

<button on:click={onClick} bind:this={buttonEl}>click me</button>

Some browsers do not support them. (Polyfills are required)
Shadow DOM is not available server-side.
Styles are encapsulated and not scoped. External/global styles will not be applied.
In the DOM, slotted content renders eagerly.

This means that it will be added even if it's not shown.

{#if condition}
<slot></slot>
{/if}

Avoid using slotted content inside #each blocks, as it will not be rerendered. As a general rule, avoid putting a <slot></slot> inside a template modifier as it will not work as expected.

Final thoughts

As you can see, there are plenty of options for developing and bundling your app and web components.

You can find a repo with the final code here.

I hope this post will help you explore what you can do with Svelte, and custom elements.

Reactivity in Svelte

Ignacio Le Fluk — Mon, 27 Dec 2021 09:20:45 +0000

Keeping your application in sync with its state is one of the most important features that a framework can provide. In this post, we'll learn about how reactivity works in Svelte, and avoid common issues when using it.

Let's start a new application to explain how it works.

npm init @vitejs/app

✔ Project name: · svelte-reactivity
✔ Select a framework: · svelte
✔ Select a variant: · svelte-ts

cd svelte-reactivity
pnpm install //use the package manager you prefer
pnpm run dev

We will remove everything we have in our App.svelte component an replace it with the following:

<!-- App.svelte -->
<script lang="ts">
    let language: 'es'|'en' = 'en';

    function toggleLanguage() {
        language = language === 'en' ? 'es' : 'en';
    }
</script>

<main>
    <p>{language}</p>
    <button on:click={toggleLanguage}>Toggle Language</button>
</main>

We added a button with an event handler responsible for toggling our variable with two values en and es.
We can see that the value is updated every time we click the button.

In Svelte, the DOM is updated when an assignment is made. In this example, language is assigned with the result of language === 'en' ? 'es' : 'en'.
Behinds the scenes, Svelte will take care of rerendering the value of language when the assignment happens.

If we take a look at the compiled code we will find this.

/* App.svelte generated by Svelte v3.38.3 */
// ...

function instance($$self, $$props, $$invalidate) {
    let language = "en";

    function toggleLanguage() {
        $$invalidate(0, language = language === "en" ? "es" : "en");
    }

    return [language, toggleLanguage];
}

// ...

We can see that our toggleLanguage function looks a bit different, wrapping the assignment with the $$invalidate method.

Let's make a few more changes to our file to see how assignment affects reactivity and rerendering.

<!-- App.svelte -->
<script lang="ts">
    let testArray = [0]

    function pushToArray(){
        testArray.push(testArray.length)
    }

    function assignToArray(){
        testArray = [...testArray, testArray.length]
    }
</script>
<main>
    <p>{testArray}</p>
    <button on:click={pushToArray}>Push To Array</button>
    <button on:click={assignToArray}>Assign To Array</button>
</main>

Whenever we click on the Assign To Array Button, the DOM is updated with the new value.
When we try to get the same result by mutating the array, the DOM is not updated, but the app state is. We can verify that when we later click the Assignment button and the DOM is updated, showing the actual state of testArray.

Let's inspect the generated code once again.

function instance($$self, $$props, $$invalidate) {
    let testArray = [0];

    function pushToArray() {
        testArray.push(testArray.length);
    }

    function assignToArray() {
        $$invalidate(0, testArray = [...testArray, testArray.length]);
    }

    return [testArray, pushToArray, assignToArray];
}

If you compare both functions, we can now see that only the assignment will call the $$invalidate method, while the other one calls the expression as is.

This doesn't mean we cannot mutate arrays and force a rerender. We need to use an assignment after mutation to do it.

<!-- App.svelte -->
<script lang="ts">
    //...

    function pushToArray(){
        testArray.push(testArray.length)
        testArray = testArray
    }

    //...
</script>

Our complied function will be updated to:

function pushToArray() {
    testArray.push(testArray.length);
    $$invalidate(0, testArray);
}

which will update the DOM when called($$invalidate method wraps the expression, that is simplified to testArray instead of testArray = testArray)

Reactive Variables

Imagine our team decided that we need to add a second array where each value is squared. If we were doing it imperatively, this would mean we need to update the second array each time the first one changes.
The previous example would look like this.

<!-- App.svelte -->
<script lang="ts">
    let testArray = [0]
    let squared = [0]

    function pushToArray(){
        testArray.push(testArray.length)
        testArray = testArray
        squared = testArray.map(value => value*value)
    }

    function assignToArray(){
        testArray = [...testArray, testArray.length]
        squared = testArray.map(value => value*value)
    }
</script>
<main>
    <p>{testArray}</p>
    <p>{squared}</p>
    <!-- ... -->
</main>

If we check the generated code again, we'll see that we are invalidating both arrays every time.

function pushToArray() {
    testArray.push(testArray.length);
    $$invalidate(0, testArray);
    $$invalidate(1, squared = testArray.map(value => value * value));
}

function assignToArray() {
    $$invalidate(0, testArray = [...testArray, testArray.length]);
    $$invalidate(1, squared = testArray.map(value => value * value));
}

Unfortunately, this approach has a problem. We need to keep track of every place where testArray is modified, and also update the squared array.

If we think about this problem reactively, we only need to listen to changes in testArray.

In Svelte, there's a special way to do this. Instead of declaring a variable with let, we will use $:. This is a labeled statement (it's valid JS), and it's used by the compiler to let it know that a reactive variable is being declared, and it depends on all the variables that are added to the expression.
In our example:

<script lang="ts">
  let testArray = [0];
  $: squared = testArray.map(value => value * value)

  function pushToArray() {
    testArray.push(testArray.length);
    testArray = testArray;
  }

  function assignToArray() {
    testArray = [...testArray, testArray.length];
  }
</script>

Using this reactive approach, we need to handle changes to testArray exclusively.
The compiler will detect that there's a dependency in testArray to calculate the actual value of squared.

If you run the app again, the same behavior is achieved.

How did this happen?
Let's look at our compiled code.

    $$self.$$.update = () => {
        if ($$self.$$.dirty & /*testArray*/ 1) {
            $: $$invalidate(1, squared = testArray.map(value => value * value));
        }
    };

The internal property update is now assigned to a function that will check if the instance has changed, and that invalidate squared if the condition is met.

Every other reactive variable we add to our component will add a new block that will check if a dependency changed, and invalidate the declared variable.
For example:

<script lang="ts">
  let testArray = [0];
  let multiplier = 5
  $: squared = testArray.map(value => value * value)
    // if ($$self.$$.dirty & /*testArray*/ 1) {
    //   $: $$invalidate(1, squared = testArray.map(value => value * value));
    // }
  $: squaredTwice = squared.map(value => value * value)
    // if ($$self.$$.dirty & /*squared*/ 2) {
    //   $: squaredTwice = squared.map(value => value * value);
    // }
  $: multiplied: squaredTwice.map(value => value * multiplier)
    // if ($$self.$$.dirty & /*squaredTwice, multiplier*/ 34) {
    //   $: multiplied = squaredTwice.map(value => value * multiplier);
    // }

</script>
<!-- ... -->

The last declaration, however, depends on two variables, squareTwice and multiplier. You can tell by the comment in the if condition.

Our updated component now looks like this:

<script lang="ts">
  let testArray = [0];
  let multiplier = 5;

  $: squared = testArray.map((value) => value * value);
  $: squaredTwice = squared.map((value) => value * value);
  $: multiplied = squaredTwice.map((value) => value * multiplier);

  function pushToArray() {
    testArray.push(testArray.length);
    testArray = testArray;
  }

  function assignToArray() {
    testArray = [...testArray, testArray.length];
  }
</script>

<main>
  <p>{testArray}</p>
  <p>{squared}</p>
  <p>{squaredTwice}</p>
  <p>{multiplied}</p>
  <button on:click={pushToArray}>Push To Array</button>
  <button on:click={assignToArray}>Assign To Array</button>
  <button on:click={() => multiplier = multiplier + 1}>Multiplier</button>
</main>

I added a button to add 1 to multiplier to verify that the multiplied array is also depending on it.

Reactive Statements

Reactivity is not limited to variable declarations. Using the same $: pattern we can create reactive statements.
For example, we could add an if statement or add a try-catch block.

Let's try the following:

<script lang="ts">
  //...
  let error = null;
  //...
  $: try {
    if (multiplier > 8) {
      throw 'boo';
    }
  } catch (e) {
    error = e;
  }
  //...
</script>

<main>
  <!-- ... -->
  {#if error}
    <p>{error}</p>
  {/if}
  <!-- ... -->
</main>

Looking at the generated code we can see the same pattern as before:

if ($$self.$$.dirty & /*multiplier*/ 2) {
    $: try {
        if (multiplier > 8) {
            throw "boo";
        }
    } catch(e) {
        $$invalidate(4, error = e);
    }
}

The compiler recognizes how the statement depends on changes to multiplier and that invalidating error is a possibility.

Store auto-subscription

A store is defined as an object that implements the following contract (at a minimum):
store = { subscribe: (subscription: (value: any) => void) => (() => void), set?: (value: any) => void }
Stores are beyond the scope of this post but they will make possible to listen for changes to a piece of your app state.
Then, we can translate this event (when the store emits a new value) into an assignment that, as we mentioned before, will update our DOM.
For example:

// stores.ts
import { writable } from 'svelte/store';
export const storeArray = writable([0]);

<!-- App.svelte -->
<script lang="ts">
  import { onDestroy } from 'svelte';
  import { storeArray } from './stores';

  let testArray;
  const unsubscribe = storeArray.subscribe((value) => {
    testArray = value;
  });
  function addValueToArray() {
    storeArray.update((value) => [...value, value.length]);
  }
  onDestroy(unsubscribe);
</script>

<main>
  <p>{testArray}</p>
  <button on:click={addValueToArray}>Add Value</button>
</main>

Whenever we update, or set our store, a new value will be emitted and assigned to testArray.

We can confirm that we are calling $$invalidate in the compiled code.

const unsubscribe = storeArray.subscribe(value => {
        $$invalidate(0, testArray = value);
    });

But there's another way to achieve this with auto-subscriptions.

Our component now becomes this:

<script lang="ts">
  import { storeArray } from './stores';
  function addValueToArray() {
    storeArray.update((value) => [...value, value.length]);
  }
</script>

<main>
  <p>{$storeArray}</p>
  <button on:click={addValueToArray}>Add Value</button>
</main>

Looking at auto subscriptions. There's no assignment in it, but our DOM is updated when we update the array. How is this achieved?

Let's analyze the output code:

function instance($$self, $$props, $$invalidate) {
    let $storeArray;
    component_subscribe($$self, storeArray, $$value => $$invalidate(0, $storeArray = $$value));

    function addValueToArray() {
        storeArray.update(value => [...value, value.length]);
    }

    return [$storeArray, addValueToArray];
}

We can see that we are calling component_subscribe with three parameters: the component, the store, and a callback function, which is invalidating our $storeArray variable.

If we go deeper and check what component_subscribe is doing underneath, we'll find the following:

export function subscribe(store, ...callbacks) {
    if (store == null) {
        return noop;
    }
    const unsub = store.subscribe(...callbacks);
    return unsub.unsubscribe ? () => unsub.unsubscribe() : unsub;
}

export function component_subscribe(component, store, callback) {
    component.$$.on_destroy.push(subscribe(store, callback));
}

... Which is doing the same as the original code.

It subscribes to the store, and returns a unsubscribe method (or an object with an unsubscribe method), and calls it when the component is destroyed. When a new value is emitted, the callback is executed ($$invalidate), assigning the emitted value to the auto-subscribe variable.

Common issues

Remember that we need an assignment to call $$invalidate mark the component instance as dirty and run all the checks.
=, ++, --, +=, -= are all considered assignments.
When working with objects, the assignment must include the name of the variable referenced in the template.
For example:

<script>
  let foo = { bar: { baz: 1 } };
  let foo2 = foo;
  function addOne() {
    foo2.bar.baz++;
  }
  function refreshFoo() {
    foo = foo;
  }
</script>
<p>foo: {JSON.stringify(foo, null, 2)}</p>
<p>foo2: {JSON.stringify(foo2, null, 2)}</p>

<button on:click={addOne}> add 1 </button>

<button on:click={refreshFoo}> Refresh foo </button>

When adding 1 to foo2.bar.baz the compiler only knows that it must update references to foo2 in the templates, but it will not update references to foo event if it changes too (they're the same object). When calling refreshFoo we are manually invalidating foo

when mutating arrays, be mindful of adding an assignment at the end to let the compiler know that it must update the template references.

Wrapping up

In general, whenever an assignment is made it will compile into an $$invalidate method that will mark the component as dirty and apply the required changes to the DOM.
If there's any reactive variable (or statement) it will check if the component is marked as dirty and if any of its dependencies changed (because it has been invalidated), if that's the case then it will also invalidate it.
Store auto subscription creates an assignment that invalidates the $ prepended variable when the store emits a new value.

Handling Forms in Svelte

Ignacio Le Fluk — Fri, 17 Dec 2021 09:30:57 +0000

If you're building an app or website, it's very likely that at some point you need to add a form to it.

In this post, we'll dive into how to handle forms in Svelte, starting from a simple approach. Then, we'll start adding complexity to it, and finally, we'll have a reusable solution.

Starting with a simple form

Let's build a sign-in form with two fields: email and password.

We'll begin by creating a new Svelte project (I prefer vite).

npm init @vitejs/app

✔ Project name: · forms-in-svelte
✔ Select a framework: · svelte
✔ Select a variant: · svelte-ts

cd forms-in-svelte
pnpm install //use the package manager you prefer
pnpm run dev

NOTE: At the moment of writing there's a bug with Svelte TypeScript projects. If you get an error, add "type":"module" in your package.json file.

Now that we have our application ready, we'll start by removing the content of App.svelte and create a sign-in form.

We should also delete the Counter component created by default.

<!-- App.svelte -->
<main>
  <form>
    <div>
        <label for="name">Email</label>
        <input
          type="text"
          id="email"
          name="email"
          value=""
        />
    </div>
    <div>
      <label for="name">Password</label>
      <input
        type="password"
        id="password"
        name="password"
        value=""
      />
  </div>
    <button type="submit">Submit</button>
  </form>
</main>

<style>
   * {
      box-sizing: border-box;
    }
    form {
      display: flex;
      flex-direction: column;
      width: 300px;
    }

    form > div{
      display: flex;
      justify-content: space-between;
    }

    form > div + * {
      margin-top: 10px;
    }
</style>

Handling the submit event

Currently, our form does nothing. We need to handle the submit event on the form. To do that, we must add a handler.

To handle a submit event, we need to add to the form element the on:submit handler.

For now, we will only parse the form, and print it in the console.

<!-- App.svelte -->
<script lang="ts">
  function onSubmit(e) {
    const formData = new FormData(e.target);

    const data = {};
    for (let field of formData) {
      const [key, value] = field;
      data[key] = value;
    }
    console.log(data)
  }
</script>

<main>
  <form on:submit|preventDefault={onSubmit}>
   <!-- ... -->
  </form>
</main>
<!-- ... -->

Note that we used the event modifier |preventDefault. This is equivalent to adding the Event preventDefault method in the handler.

Adding validation

Now that our form "works", we can add more features to it. For example, we may want to add some validation when the form is submitted. We will make both inputs required. If the form is invalid, we will print an error in the console. Otherwise, we will print the form data.

<!-- App.svelte -->
<script lang="ts">
  function isFormValid(data: {[fieldName: string]: any}): boolean {
    if(!isRequiredFieldValid(data.email)){
      return false
    }

    if(!isRequiredFieldValid(data.password)){
      return false
    }
    return true
  }

  function isRequiredFieldValid(value){
    return value != null && value !== ""
  }

  function onSubmit(e) {
    const formData = new FormData(e.target);

    const data: any = {};
    for (let field of formData) {
      const [key, value] = field;
      data[key] = value;
    }
    if(isFormValid(data)){
      console.log(data)
    } else {
      console.log("Invalid Form")
    }
  }
</script>
<!-- ... -->

Displaying errors

Now, our form is running a simple validation on submit, but we are missing feedback for the user. It's time to display some errors in case something fails.

<!-- App.svelte -->
<script lang="ts">
  let errors: { [inputName: string]: any } = {};

  function isFormValid(data: { [inputName: string]: any }): boolean {
    return !Object.keys(errors).some((inputName) =>
      Object.keys(errors[inputName]).some(
        (errorName) => errors[inputName][errorName],
      ),
    );
  }

  function validateForm(data: { [inputName: string]: any }):void {
    if (!isRequiredFieldValid(data.email)) {
      errors['email'] = { ...errors['email'], required: true };
    } else {
      errors['email'] = { ...errors['email'], required: false };
    }

    if (!isRequiredFieldValid(data.password)) {
      errors['password'] = { ...errors['password'], required: true };
    } else {
      errors['password'] = { ...errors['password'], required: false };
    }
  }

  function isRequiredFieldValid(value) {
    return value != null && value !== '';
  }

  function onSubmit(e) {
    const formData = new FormData(e.target);

    const data: any = {};
    for (let field of formData) {
      const [key, value] = field;
      data[key] = value;
    }

    validateForm(data);

    if (isFormValid(data)) {
      console.log(data);
    } else {
      console.log('Invalid Form');
    }
  }
</script>

<main>
  <form on:submit|preventDefault={onSubmit}>
    <div>
      <label for="name">Email</label>
      <input type="text" id="email" name="email" value="" />
      {#if errors.email && errors.email.required}
        <p class="error-message">Email is required</p>
      {/if}
    </div>
    <div>
      <label for="name">Password</label>
      <input type="password" id="password" name="password" value="" />
      {#if errors.password && errors.password.required}
        <p class="error-message">Password is required</p>
      {/if}
    </div>
    <button type="submit">Submit</button>
  </form>
</main>

<style>
  /* ... */

  form > div {
    display: flex;
    flex-wrap: wrap;
    justify-content: space-between;
  }

  /* ... */

  .error-message {
    color: tomato;
    flex: 0 0 100%;
    margin: 0 2px;
    font-size: 0.8em;
  }
</style>

First, I created an error object to keep track of each field, and its errors. I created it as an empty object as I expect it to be populated when verification happens.

Three functions will help validation:

isRequiredFieldValid checks if a given value is null, undefined, or an empty string.
validateForm sets errors to true or false for each form input. In this example, we are checking if both required fields are valid.
isFormValidwill check if there's an error in the form.

In the template, error messages are added below each form input, with a message to be displayed if the error is present and true.

Finally, some CSS was added for styling the form.

The result looks something like this:

Preparing for reusability

We have a working form right now, but it would be better if somehow we could make our form reusable.

The pattern will be repeated for each input we add. It would be nice if we could make it configurable, or if we could easily add more errors and validators without repeating ourselves.

Let's move the validators to a new file, and add more information to the response.

// Validators.ts
export interface ValidatorResult {
  [validatorName: string]: {
    error: boolean;
    message?: string;
  };
}

export type ValidatorFn = (value: any) => ValidatorResult;

function required(value: any): ValidatorResult {
  if (value === '' || value == null) {
    return { required: { error: true, message: 'Field is required' } };
  }
  return { required: { error: false } };
}

export const Validators = {
  required,
};

Previously, we had the isRequiredFieldValid method returning just a boolean. Now it returns an object with the error name required, error status, and a message, but can be extended with more information if required.

We now need to make use of this new Validator in our App component.

<!-- App.svelte -->
<script lang="ts">
  import { Validators } from './lib/Validators';
  import type { ValidatorFn, ValidatorResult } from './lib/Validators';

  let errors: { [inputName: string]: ValidatorResult } = {};

  let form: {
    [inputName: string]: {
      validators: ValidatorFn[];
    };
  } = {
    email: {
      validators: [Validators.required],
    },
    password: {
      validators: [Validators.required],
    },
  };

  function isFormValid(): boolean {
    return !Object.values(errors).some((field) =>
      Object.values(field).some((errorObject) => errorObject.error),
    );
  }

  function validateForm(data: { [inputName: string]: any }): void {
    Object.keys(data).forEach((field) => validateField(field, data[field]));
  }

  function validateField(field, value) {
    form[field]?.validators &&
      form[field].validators.forEach((fn) => {
        const error = fn(value);
        errors[field] = { ...errors[field], ...error };
      });
  }

  function onSubmit(e) {
    const formData = new FormData(e.target);

    const data: any = {};
    for (let field of formData) {
      const [key, value] = field;
      data[key] = value;
    }

    validateForm(data);

    if (isFormValid()) {
      console.log(data);
    } else {
      console.log('Invalid Form');
    }
  }
</script>

<main>
  <form on:submit|preventDefault={onSubmit}>
    <div>
      <label for="name">Email</label>
      <input type="text" id="email" name="email" value="" />
      {#if errors?.email?.required?.error}
        <p class="error-message">Email is required</p>
      {/if}
    </div>
    <div>
      <label for="name">Password</label>
      <input type="password" id="password" name="password" value="" />
      {#if errors?.password?.required?.error}
        <p class="error-message">Password is required</p>
      {/if}
    </div>
    <button type="submit">Submit</button>
  </form>
</main>

<!-- ... -->

First, I've created a form object that contains the different input names with a list of the validators that should be checked for each of them.

I added the required validator for both of them.

Then we will run all validators in the form object where the key matches the name of the input element.

The template has been updated too to handle the validator response object.

With this small refactoring, we've preserved our previous behavior, but opened the door to expand our form.

More validators

Let's add another validator to our password input.

We'll check if the password has a minimum length of 6 characters.

We'll start by creating a new validator. The best way is to use a higher-order function to set up the length, and return our validator function from it.

export interface ValidatorResult {
  [validatorName: string]: {[key:string]:any} & {
    error: boolean;
    message?: string;
  };
}

// ...

function minLength(number) {
  return function (value): ValidatorResult {
    if (value == null || value.length < number) {
      return {
        minLength: {
          error: true,
          value: number, 
          message: `Field minimum length is ${number}`,
        },
      };
    }
    return { minLength: { error: false } };
  };
}

export const Validators = {
  required,
  minLength
};

Now, we need to add it to our form configuration object, and handle the error in the template. We are using the error default message.

<!-- App.svelte -->
<script lang="ts">
// ...
  let form: {
    [inputName: string]: {
      validators: ValidatorFn[];
    };
  } = {
    email: {
      validators: [Validators.required],
    },
    password: {
      validators: [Validators.required, Validators.minLength(6)],
    },
  };

 //...
</script>

<main>
  <form on:submit|preventDefault={onSubmit}>
   <!-- ... -->
    <div>
      <label for="name">Password</label>
      <input type="password" id="password" name="password" value="" />
      {#if errors?.password?.required?.error}
        <p class="error-message">Password is required</p>
      {/if}
      {#if errors?.password?.minLength?.error}
        <p class="error-message">{errors.password.minLength.message}</p>
      {/if}
    </div>
    <button type="submit">Submit</button>
  </form>
</main>

<!-- ... -->

Handling other form events

I want to add another feature to our form. I want to validate each field separately on blur.

We can use an event handler with one of each input element to do it.

<!-- App.svelte -->
<script lang="ts">
  //...

  function onBlur(e){
    validateField(e.target.name, e.target.value)
  }

</script>

<main>
  <form on:submit|preventDefault={onSubmit}>
    <!-- ... -->
      <input type="text" id="email" name="email" value="" on:blur={onBlur} />
    <!-- ... -->
      <input type="password" id="password" name="password" value="" on:blur={onBlur} />
       <!-- ... -->
  </form>
</main>

<!-- ... -->

We just added an on:blur event handler, and onBlur method to take care of everything. Now, everytime an input loses focus it will be validated.

Our form is working as expected. However, I'd like to move it to a new component.

Creating a reusable form component

Let's create a new component Form.svelte, and move most of the form logic into it.

The form configuration should remain in the App component, and be passed into the new Form component.

<!-- Form.svelte -->
<script lang="ts">
  import { setContext } from 'svelte';
  import type { ValidatorFn, ValidatorResult } from './Validators';
  import { createEventDispatcher } from 'svelte';
  import { writable } from 'svelte/store';

  export let form: {
    [inputName: string]: {
      validators: ValidatorFn[];
    };
  } = {};

  let formEl;

  const dispatch = createEventDispatcher();
  let errors = writable({});

  function onBlur(e) {
    validateField(e.target.name, e.target.value);
  }

  function isFormValid(): boolean {
    return !Object.values($errors).some((field) =>
      Object.values(field).some(
        (errorObject: ValidatorResult) => errorObject.error,
      ),
    );
  }

  function validateField(field, value) {
    form[field]?.validators &&
      form[field].validators.forEach((fn) => {
        const error = fn(value);
        errors.update((e) => {
          e[field] = { ...e[field], ...error };
          return e;
        });
      });
  }

  function validateForm(data: { [inputName: string]: any }): void {
    Object.keys(data).forEach((field) => validateField(field, data[field]));
  }

  function onSubmit(e) {
    const formData = new FormData(e.target);

    const data: any = {};
    for (let field of formData) {
      const [key, value] = field;
      data[key] = value;
    }
    validateForm(data);

    return dispatch('submit', { valid: isFormValid(), data });
  }

  export function reset() {
    formEl.reset();
  }

  setContext('form', { errors, onBlur });
</script>

<form on:submit|preventDefault={onSubmit} bind:this={formEl}>
  <slot />
</form>

<style>
  form {
    display: flex;
    flex-direction: column;
    width: 300px;
  }

  :global(form > div) {
    display: flex;
    flex-wrap: wrap;
    justify-content: space-between;
  }

  :global(form > div + *) {
    margin-top: 10px;
  }
</style>

The template is very simple. A form element with a slot.

We are also binding the form element, and the on:submit event.

There's only one input: form, which will be in charge of passing data from the parent component.

The element's binding will be used to expose the native reset method from the form element. And the event binding will be used to perform validations, and emit a new submit event to be handled by the parent component.

One important thing to notice is that, to communicate the slotted elements with the Form component, we will use the Context API. There's one caveat though, context is not reactive. But, we can make it reactive by making its content a store.

Currently, we will only need to pass two things to the slotted content, the onBlur method, and the errors object. Because we expect the error object to be changing, I rewrote it as a writable store. Note that everything that previously used the errors object will have to use this new store.

To keep the parent component simple (the one containing the form), the form content will be wrapped in new components that will make use of the context API to get the data from the Form component.

Because I want always to have a label for any given field, I'll make it part of the Input component, and because I want to add validation on blur, I'll get the onBlur method exposed by the Form component through the context API.

<!-- Input.svelte -->
<script lang="ts">
  import { getContext } from 'svelte';
  export let type = 'text';
  export let label;
  export let name;
  const { onBlur } = getContext('form');
</script>

<label for={name}>{label}</label>
<input {name} {type} on:blur={onBlur} />

We are closer to getting the same behavior as before, but we are missing the error components. We can wrap all that functionality in a single component, and get the error information through the context API.

<!-- Error.svelte -->
  import { getContext } from 'svelte';
  const { errors } = getContext('form');
  export let message = null;
  export let fieldName;
  export let errorKey;
</script>

{#if $errors?.[fieldName]?.[errorKey]?.error}
  <p class="error-message">{message || $errors[fieldName][errorKey].message}</p>
{/if}

<style>
  .error-message {
    color: tomato;
    flex: 0 0 100%;
    margin: 0 2px;
    font-size: 0.8em;
  }
</style>

We are now reading the value from the errors store to decide if the message should be shown or not.

We are also using a default message from the validator in case no message is provided.

Now that all the pieces are ready, we can update our App component.

<!-- App.svelte -->
<script lang="ts">
  import { Validators } from './lib/Validators';
  import Form from './lib/Form.svelte';
  import Input from './lib/Input.svelte';
  import Error from './lib/Error.svelte';

  let formEl;
  let form = {
    email: {
      validators: [Validators.required],
    },
    password: {
      validators: [Validators.required, Validators.minLength(6)],
    },
  };

  function onSubmit(e) {
    if (e?.detail?.valid) {
      console.log(e.detail.data);
      setTimeout(() => formEl.reset(), 1000)
    } else {
      console.log('Invalid Form');
    }
  }
</script>

<main>
  <Form {form} on:submit={onSubmit} bind:this={formEl}>
    <div>
      <Input label="Email" name="email" />
      <Error
        fieldName="email"
        errorKey="required"
        message="Email is required"
      />
    </div>
    <div>
      <Input label="Password" name="password" />
      <Error
        fieldName="password"
        errorKey="required"
        message="Password is required"
      />
      <Error fieldName="password" errorKey="minLength" />
    </div>
    <button type="submit">Submit</button>
  </Form>
</main>

<style>
  * {
    box-sizing: border-box;
  }
</style>

Our app component now only needs to set up the validators, handle the submit event, and can reset the form if needed.

Extending the form component

Our form component is now exposing just a few things emitted on the submit event, or through the context API, for the slotted components.

Similar to what we've done with the input field, we must extend the functionality for select, radio buttons, checkboxes, or any other form control that we want.

For example, this is how a select component may look like.

<!-- Select.svelte -->
<script lang="ts">
  import { getContext } from 'svelte';
  export let label;
  export let name;
  const { onBlur } = getContext('form');
</script>

<label for={name}>{label}</label>
<select {name} on:blur={onBlur}>
  <slot />
</select>

And this is how it could be used:

<!-- App.svelte -->
<script lang="ts">
  import { Validators } from './lib/Validators';
  import Form from './lib/Form.svelte';
  import Input from './lib/Input.svelte';
  import Error from './lib/Error.svelte';
  import Select from './lib/Select.svelte';

  let form = {
    name: {
      validators: [Validators.required],
    },
    food: {
      validators: [Validators.required],
    },
  };

  let formEl;

  function onSubmit(e) {
    if (e?.detail?.valid) {
      console.log(e.detail.data);
      setTimeout(() => formEl.reset(), 1000)
    } else {
      console.log('Invalid Form');
    }
  }
</script>

<main>
  <Form {form} on:submit={onSubmit} bind:this={formEl}>
    <div>
      <Input label="Name" name="name" />
      <Error
        fieldName="name"
        errorKey="required"
        message="Name is required"
      />
    </div>
    <div>
      <Select label="Favorite food" name="food">
        <option value="chocolate">Chocolate</option>
        <option value="pizza">Pizza</option>
      </Select>
    </div>
    <button type="submit">Submit</button>
  </Form>
</main>
<!-- ... -->

Available Libraries

There are plenty of available libraries for handling forms in Svelte. You can check some of them in this list.

Final thoughts

I hope this step-by-step guide to handling forms helps you find your own solution to handling them, or gives you a better understanding of how other libraries might be working.

Intro to Svelte

Ignacio Le Fluk — Sun, 12 Dec 2021 13:56:25 +0000

Svelte is a JavaScript tool that may look similar to other frameworks, or have similar concepts, but it works differently, making it stand out from the rest.
Svelte is reactive by nature, and instead of using a virtual dom, it will directly update the DOM in an efficient way.

It is possible to achieve this by delegating its work to a compile step, which will make the framework itself "disappear", and will ship some optimized vanilla JavaScript code.

Let's take a look at an example of a Svelte component.

<!-- App.svelte -->
<h1>This is Svelte</h1>
<p class="omg">It looks like regular html</p>

As you can see, at a first glance, it is no different than plain old HTML (for a non-dynamic component). You can keep using the class keyword.

Let's add some CSS to our component.

<!-- App.svelte -->
<h1>This is Svelte</h1>
<p class="omg">It looks like regular html</p>
<p class="styled">CSS rocks!</p>

<style>
  h1 {
    font-size: 30px;
  }
  .styled {
    color: red;
  }
</style>

Once again, this looks like regular CSS, and that's because it is regular CSS.

How about adding some JS to it?

<!-- App.svelte -->
<script>
  function logSomething(something) {
    console.log(something);
  }

  logSomething('it works');
</script>

<h1>This is Svelte</h1>
<p class="omg">It looks like regular html</p>
<p class="styled">CSS rocks!</p>

<style>
  h1 {
    font-size: 30px;
  }
  .styled {
    color: red;
  }
</style>

So, we have HTML that looks like HTML, CSS that looks like CSS, and JavaScript that looks like JavaScript, all packed in a single svelte file.

Of course, this is not everything Svelte has to offer.

How to start a new Svelte project

To start a svelte project, you can use the command npx degit [sveltejs/template](https://github.com/sveltejs/template) my-svelte-project as suggested on their website, but my preferred way of doing it these days is to use vite.

Both methods can be set up to use TypeScript.

Let's create a new project.

npm init @vitejs/app

✔ Project name: · my-svelte-project
✔ Select a framework: · svelte
✔ Select a variant: · TypeScript

cd my-svelte-project
pnpm install //use the package manager you prefer
pnpm run dev

Now that our project is created, it will have a folder structure that looks like this.

How do you do x in Svelte?

Let's create a new component to be able to test different features of Svelte. I will remove the default component created (Counter.svelte)

rm -rf src/lib/Counter.svelte     // removes the component created by default
touch src/lib/Example.svelte      // creates a new svelte component

We need to update App.svelte to import our new component and render it

<!-- App.svelte -->
<script>
  import Example from './lib/Example.svelte';
</script>

<Example />

Using variables in the template

To use a variable in the template we need to:
Declare a variable in our <script>
Use the variable within brackets {} in the template

In our component:

<!-- src/lib/Example.svelte -->
<script lang="ts">
  let greeting: string = 'Hi';
</script>

<p>{greeting}</p>

If you run the application with the command npm run dev, the project will start, and run by default on port 3000. Changes will be reflected in the browser.

props/inputs

To create an input we need to export a variable.

<!-- src/lib/Example.svelte -->
<script lang="ts">
  export let name: string;
  let greeting: string = 'Hi';
</script>

<span>{greeting}, {name}</span>

We will need to update our App to pass the value of name.

<!-- App.svelte -->
<script>
  import Example from './lib/Example.svelte';
</script>

<Example name="John" />

Event

You can listen to events with the on directive.

Let's add an event to our span element in the Example component.

<script lang="ts">
  export let name: string;
  let greeting: string = 'Hi';

  function toggleGreeting() {
    if (greeting === 'Hi') {
      greeting = 'Bye';
    } else {
      greeting = 'Hi';
    }
  }
</script>

<p>{greeting}, {name}</p>
<button on:click={toggleGreeting}>Toggle greeting</button>

You can now see the text changing when clicking on the button.

Sometimes you will need to pass a custom event from a child component to a parent component. To trigger a custom event we need to import and use the createEventDispatcher method.

<script lang="ts">
  import { createEventDispatcher } from 'svelte';

  const dispatch = createEventDispatcher();

  export let name: string;
  let greeting: string = 'Hi';

  function toggleGreeting() {
    if (greeting === 'Hi') {
      greeting = 'Bye';
    } else {
      greeting = 'Hi';
    }
  }

  function toggleName() {
    dispatch('myCustomEvent');
  }
</script>

<p>{greeting}, {name}</p>
<button on:click={toggleGreeting}>Toggle greeting</button>
<button on:click={toggleName}>Toggle Name</button>

We need to update our App component too, to do something with the event.

<script>
  import Example from './lib/Example.svelte';

  let name = 'John';
  function onMyCustomEvent() {
    if (name === 'John') {
      name = 'Jane';
    } else {
      name = 'John';
    }
  }
</script>

<Example {name} on:myCustomEvent={onMyCustomEvent} />

This event can pass data using the second argument in the dispatch method.

<!-- src/lib/Example.svelte -->

<script lang="ts">
  import { createEventDispatcher } from 'svelte';

  const dispatch = createEventDispatcher();

  export let name: string;
  let greeting: string = 'Hi';

  function toggleGreeting() {
    if (greeting === 'Hi') {
      greeting = 'Bye';
    } else {
      greeting = 'Hi';
    }

    let nextName;
    if (name === 'John') {
      nextName = 'Jane';
    } else {
      nextName = 'John';
    }
  }

  function toggleName() {
    let nextName;
    if (name === 'John') {
      nextName = 'Jane';
    } else {
      nextName = 'John';
    }
    dispatch('myCustomEvent', nextName);
  }

</script>

<p>{greeting}, {name}</p>
<button on:click={toggleGreeting}>Toggle greeting</button>
<button on:click={toggleName}>Toggle Name</button>

<script>
  import Example from './lib/Example.svelte';

  let name = 'John';
  function onMyCustomEvent(event) {
    name = event.detail;
  }
</script>

<Example {name} on:myCustomEvent={onMyCustomEvent} />

Now the Example component is emitting an event with the new name. And the App component is handling it.

Reactivity

One of the main features of svelte is that it makes reactivity so easy to reason about.

To include a reactive statement, you need to prepend it with $:.
The compiler will figure out when it should update the reactive values based on the variables that it depends on.
In our previous example:

<!-- src/lib/Example.svelte -->

<script lang="ts">
  import { createEventDispatcher } from 'svelte';

  const dispatch = createEventDispatcher();

  export let name: string;
  let greeting: string = 'Hi';

  $: reactiveValue = `You're saying ${greeting} to ${name}`

  function toggleGreeting() {
    if (greeting === 'Hi') {
      greeting = 'Bye';
    } else {
      greeting = 'Hi';
    }

    let nextName;
    if (name === 'John') {
      nextName = 'Jane';
    } else {
      nextName = 'John';
    }
  }

  function toggleName() {
    let nextName;
    if (name === 'John') {
      nextName = 'Jane';
    } else {
      nextName = 'John';
    }
    dispatch('myCustomEvent', nextName);
  }

</script>

<p>{greeting}, {name}</p>
<p>{reactiveValue}</p>
<button on:click={toggleGreeting}>Toggle greeting</button>
<button on:click={toggleName}>Toggle Name</button>

In this example, reactiveVlaue is dependant on name and greeting. Whenever any of these values changes, reactiveValue will be updated.

Reactivity in Svelte will be triggered by assignments, which means that it's required to assign a value to make it work. Array.prototype.push is not an assignment, so it will not work.

Flow control

if/else
You can change your template rendering based on some condition use if else. The syntax looks like this

{#if <condition>}
    some code
{:else if}
    more code
{:else}
    more code
{/if}

The syntax is similar to other template modifiers. start with {# }, continue with {: } and end with {/ }.

each
You can iterate over an array with an each block.

{#each anArray as item, i}
<span>{item.name}{/span}
{/each}

When iterating this way and modifying the array, items will be added or removed at the end of the block, and the values of the items will be updated accordingly.

If you need to keep track of each element, you can use a key. This is common for other frameworks too.

The syntax for this is:

{#each anArray as item (item.id)}
<span>{item.name}{/span}
{/each}

where the id is the unique key in this example.

Asynchronous rendering

Sometimes, you need to wait before rendering something (or not). We can make use of an async block in this case.
Similar to the other template modifiers, the syntax is like this.

{#await aPromise}
    <p>Somthing to render while promise has not resolved
{:then value}
    <p>If the promise is successful you can render the value: {value}</p>
{:catch error}
    <p>There was an error: {error.message}</p>
{/await}

Stores

Another nice feature of svelte is stores, which provides a way of having global pieces of state in your application. They can be accessed anywhere in your application, and are reactive.

A readable store cannot be modified from the outside (like a component). A writable store can be accessed and updated from a component.
The third kind of store is a derived store, which will depend on other stores, and update accordingly.

Let's share some state between components using a store:

// lib/stores.ts
import { writable } from 'svelte/store';

export const age = writable(32);

<!-- src/lib/Example.svelte -->

<script lang="ts">
  import { createEventDispatcher } from 'svelte';
  import { age } from './stores.js';

  const dispatch = createEventDispatcher();

  export let name: string;
  let greeting: string = 'Hi';

  $: reactiveValue = `You're saying ${greeting} to ${name}`

  function toggleGreeting() {
    if (greeting === 'Hi') {
      greeting = 'Bye';
    } else {
      greeting = 'Hi';
    }
  }

  function toggleName() {
    let nextName;
    if (name === 'John') {
      nextName = 'Jane';
    } else {
      nextName = 'John';
    }
    dispatch('myCustomEvent', nextName);
  }

   function toggleAge() {
    age.update(value => value === 32 ? 35 : 32);
  }

</script>

<p>{greeting}, {name}</p>
<p>{reactiveValue}</p>
<button on:click={toggleGreeting}>Toggle greeting</button>
<button on:click={toggleName}>Toggle Name</button>
<button on:click={toggleAge}>Toggle Age</button>

<!-- src/lib/Age.svelte -->

<script lang="ts">
  import { age } from './stores';
</script>

<span>Your age is: {$age}</span>

<script>
  import Example from './lib/Example.svelte';
  import Age from './lib/Age.svelte';

  let name = 'John';
  function onMyCustomEvent(event) {
    name = event.detail;
  }
</script>

<Example {name} on:myCustomEvent={onMyCustomEvent} />
<Age />

Svelte is a fully-featured framework that shifts some of the load to the compiler process. There's more to it like animations and context. So make sure to keep an eye on it, and give it a try whenever you can.

Sapper

Sapper is a framework built on top of Svelte, which adds more to it like router navigations, SSG, and SSR.
It never reached v1.0, but it led the way for the future of Svelte.

Svelte-Kit and the future

Announced last year, Svelte-Kit takes what's learned in Svelte and Sapper, and combines them into one single tool/framework, so you don't have to decide to either use Sapper or regular Svelte. It preserves the main features of Sapper, like file-based routing, SSR, and SSG.
It's still in Beta, but you can try it today. (I already migrated a Sapper site). Svelte-Kit uses Vite by default.

If you want to give it a try, you can start a new project by running npm init svelte@next my-app.

Angular Elements: Why?

Ignacio Le Fluk — Sat, 21 Dec 2019 04:14:22 +0000

In this post, I'll answer the same questions that I had when I started using Angular Elements.

First of all, what are Angular Elements?

Angular Elements are regular Angular Components that have been packaged as Custom Elements. Custom Elements are part of Web Components and allow us to create new HTML elements, that can be used directly on our page, or by using a polyfill if they are not supported by the browser.

There are two types of custom elements:

Customized built-in elements. They inherit from other basic HTML elements (<p>, <span>, etc)
Autonomous custom elements, which are standalone and don't inherit from other HTML elements.

Support for these types of elements vary from browser to browser, but autonomous custom elements have broader support.

How do custom elements work?

To register a custom element on the page, we must use the CustomElementRegistry.define() method.

customElements.define('my-element', MyElement);

The first parameter is a string that defines the tag that will be used for the element. The custom element's specifications require that the element name contain a dash. The second parameter is a class that contains the behavior of the new element. There's an optional third parameter, required when creating a customized built-in element, that declares which element we are extending.

Now we should be able to use the tag <my-element></my-element>.

Angular elements will take our Angular Component, and package it in a class that can be used by the define() method. That's it!

...

Not really.

Let's take a deeper look at how to generate and use these custom elements in different contexts.

Angular elements in an angular application.

We'll create a new project.

ng new my-app
cd my-app

In order to use Angular Elements, we need to add the @angular/elements library.

ng add @angular/elements

Now let's generate a component. (The source component for the custom element)

ng g c awesome-element

To generate and use our custom element in our application, we need to do a few steps:

Add our component to the entryComponents list of our module
Use the createAngularElement method of @angular/elements to create a custom element class based on the angular component
Register the custom element with the browser
Add the CUSTOM_ELEMENTS_SCHEMA to tell Angular that we will be using tags that it will not recognize because they are custom elements.

Our AppModule will look like this.

// ...
import { BrowserModule } from '@angular/platform-browser';
import { NgModule, CUSTOM_ELEMENTS_SCHEMA, Injector } from '@angular/core';
import { createCustomElement } from '@angular/elements';
// ...

@NgModule({
  declarations: [AppComponent, AwesomeElementComponent],
  imports: [BrowserModule],
  entryComponents: [AwesomeElementComponent], // (1)
  bootstrap: [AppComponent],
  schemas: [CUSTOM_ELEMENTS_SCHEMA], // (4)
})
export class AppModule {
  constructor(public injector: Injector) { 
    const el = createCustomElement(AwesomeElementComponent, { injector }); //(2)
    customElements.define('my-component', el); //(3)
  }
}

Now, we can use the element using the selector of the define method (not the one in the component), just like any other HTML tag.

<my-component></my-component>

One important thing to be aware of is that custom elements require that you use es6 classes. If you are targeting es5, you will need to use polyfills.

There are useful polyfills that can help you if you are targeting older browsers or es5.

webcomponents-bundle.js: Will load all the polyfills.
webcomponents-loader.js: that dynamically loads the minimum polyfill bundle required.
custom-elements-es5-adapter.js: For browsers that support Custom Elements but the code is compiled to es5.

These polyfills can be added to the polyfills.ts file of your project or loaded from a CDN.

Mapping inputs and outputs

We created a simple component that displays a simple message, but we might need to add inputs and outputs. We don't need to do anything different for our custom element that we would normally do with an Angular Component. Angular elements will be in charge of creating a bridge between component inputs and custom element attributes. Because attributes won't differentiate between upper and lowercase, the input name will be converted to a dash-separated lowercase name. Outputs will become HTML custom events, preserving its name, unless an alias is set, which will be used instead.

awesome-element.component.ts

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

@Component({
  selector: 'app-awesome-element',
  templateUrl: './awesome-element.component.html',
  styleUrls: ['./awesome-element.component.css'],
})
export class AwesomeElementComponent implements OnInit {
  @Input() myInput = ''; //mapped to my-input attribute
  @Output() myOutput = new EventEmitter<string>();  //mapped to myOutput native event
  constructor() {}

  ngOnInit() {}
}

awesome-element.component.html

<p>{{myInput}}</p>
<button (click)="myOutput.emit('hello event!')">CLICK</button>

app.component.ts

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

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
})
export class AppComponent implements AfterViewInit {
  @ViewChild('comp', { static: true }) comp;

  ngAfterViewInit() {
    this.comp.nativeElement.addEventListener('myOutput', (e) => {
      console.log(e.detail ); // hello event!
    });
  }
}

app.component.html

<my-component my-input="hello input!" #comp></my-component>

Building for external application

If you plan to build your web component, you will have to make some modifications when bootstrapping your app. Because I want to keep both examples together (using the component in an angular app, and building for external use), I will create a new folder named elements, containing a modified version of some files.

src/elements/main.ts

import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { environment } from '../environments/environment';
import { ElementsModule } from './elements.module';


if (environment.production) {
  enableProdMode();
}

platformBrowserDynamic()
  .bootstrapModule(ElementsModule)
  .catch(err => console.error(err));

src/elements/elements.module.ts

import { BrowserModule } from '@angular/platform-browser';
import { NgModule, Injector, DoBootstrap } from '@angular/core';
import { AwesomeElementComponent } from '../app/awesome-element/awesome-element.component';
import { createCustomElement } from '@angular/elements';

@NgModule({
  declarations: [AwesomeElementComponent],
  imports: [BrowserModule],
  entryComponents: [AwesomeElementComponent],
  exports: [AwesomeElementComponent]
})
export class ElementsModule implements DoBootstrap {
  constructor(private injector: Injector) {
    const element = createCustomElement(AwesomeElementComponent, { injector });
    customElements.define('my-component', element);
  }

  ngDoBootstrap() {}
}

}

src/elements/index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Angular Elements</title>
    <base href="/" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" type="image/x-icon" href="favicon.ico" />
  </head>
  <body>
    <h1>Angular elements + static site</h1>
    <my-component my-input="hello-static"></my-component>
    <script>
      document.querySelector('my-component').addEventListener('myOutput', e => {
        console.log(e.detail);
      });
    </script>
  </body>
</html>

One of the main differences is in the elements.module.ts file. We've removed all the references to the AppComponent. Also, we removed the bootstrap property of the NgModule decorator. Instead, we add the ngDoBootstrap method, used for manual bootstrapping, and do nothing in it.

index.html does not make any reference to the app. Instead, it will use the custom element directly.

We need to build the component using the same command we used before, but passing the proper parameters.

ng build --main=src/elements/main.ts --index=src/elements/index.html --outputPath=dist/elements

You can add the whole command to the scripts section of package.json

We can now serve the static generated site. I'm using http-server for its simplicity.

http-server dist/elements/

The static site will now be served on port 8080.

We can see, from the build output, that lots of files were generated. If we look at the output index.html file, we will notice that all of them have been added at the end of the body of the page.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Angular Elements</title>
    <base href="/" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" type="image/x-icon" href="favicon.ico" />
  </head>
  <body>
    <h1>Angular elements + static site</h1>
    <my-component my-input="hello-static"></my-component>
    <script>
      document.querySelector('my-component').addEventListener('myOutput', e => {
        console.log(e.detail);
      });
    </script>
  <script src="runtime-es2015.js" type="module"></script><script src="runtime-es5.js" nomodule defer></script><script src="polyfills-es5.js" nomodule defer></script><script src="polyfills-es2015.js" type="module"></script><script src="styles-es2015.js" type="module"></script><script src="styles-es5.js" nomodule defer></script><script src="scripts.js" defer></script><script src="vendor-es2015.js" type="module"></script><script src="vendor-es5.js" nomodule defer></script><script src="main-es2015.js" type="module"></script><script src="main-es5.js" nomodule defer></script></body>
</html>

Depending on the browser, es5 or es2015 files will be loaded (Differential loading).

This worked fine because the CLI is taking care of adding the proper files to the page, but in terms of portability, this may not be the best option. To make your life easier, you can concatenate these files in two bundles (es5 and es2015). These bundles must be added to your site using the same differential loading techniques used before.

When building for production, disable the hashes in the filenames. To make the bundling easier.

I use a script for this purpose.

const path = require('path');
const fs = require('fs');
const distFolder = path.join(__dirname, 'dist', 'elements');
const bundlesFolder = path.join(__dirname, 'dist', 'bundles');

async function bundle(format) {
  const files = await Promise.all([
    readFile(path.join(distFolder, `runtime-${format}.js`)),
    readFile(path.join(distFolder, `polyfills-${format}.js`)),
    readFile(path.join(distFolder, `scripts.js`)),
    readFile(path.join(distFolder, `main-${format}.js`)),
  ]);

  try {
    await writeFile(
      path.join(bundlesFolder, `bundle-${format}.js`),
      files.join('\n'),
    );
  } catch (e) {
    console.error(e);
  }
}

async function bundleAll() {
  if (!fs.existsSync(bundlesFolder)) {
    fs.mkdirSync(bundlesFolder);
  }
  await Promise.all([bundle('es5'), bundle('es2015')]);
}

async function readFile(filePath) {
  return await new Promise((resolve, reject) => {
    fs.readFile(filePath, { encoding: 'utf-8' }, (err, data) => {
      if (err) {
        reject(`Error reading ${filePath}`);
      }
      resolve(data);
    });
  });
}

async function writeFile(filePath, data) {
  await new Promise((resolve, reject) => {
    fs.writeFile(filePath, data, (err, data) => {
      if (err) {
        reject(`Error writing ${filePath}`);
      }
      resolve(data);
    });
  });
}

bundleAll();

For building and bundling for production, we can run the command:

ng build --main=src/elements/main.ts --index=src/elements/index.html --outputPath=dist/elements --outputHashing=none --prod && node bundle.js

comment AwesomeElementComponent usages in the AppModule if you see an error after executing the command above

Now, we can use the bundles on any page.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Angular Elements</title>
    <base href="/" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" type="image/x-icon" href="favicon.ico" />
    <link rel="stylesheet" href="styles.css" />
  </head>

  <body>
    <h1>Angular elements + Bundles</h1>
    <my-component my-input="hello-bundle"></my-component>
    <script>
      document.querySelector('my-component').addEventListener('myOutput', e => {
        console.log(e.detail);
      });
    </script>
    <script src="bundle-es2015.js" type="module"></script>
    <script src="bundle-es5.js" nomodule defer></script>
  </body>
</html>

Why should I use Angular Elements?

You are migrating from AngularJS to Angular (allows a gradual migration).
You have a static site, and you just want to embed a complex component to it.
You have a large team working with different technologies, and you want to share some parts of your app.

Final words

I hope you found this article helpful. There's still room for Angular Elements to improve bundling size and tooling. Hopefully, Ivy will also add some improvements.
You can find the final code in here

This Dot Inc. is a consulting company which contains two branches : the media stream and labs stream. This Dot Media is the portion responsible for keeping developers up to date with advancements in the web platform. In order to inform authors of new releases or changes made to frameworks/libraries, events are hosted, and videos, articles, & podcasts are published. Meanwhile, This Dot Labs provides teams with web platform expertise using methods such as mentoring and training.

Fullstack development with Bazel

Ignacio Le Fluk — Fri, 01 Nov 2019 22:21:40 +0000

One of the benefits of using Bazel is the possibility to use it across the whole stack, and establish relationships between different parts of your application. Backend and frontend do not have to live in isolation.
I want to start exploring full stack development using only JavaScript/TypeScript, because it will allow us to use the @bazel/bazel package.

We'll start by creating an Angular application with Bazel. Why? Because I want the CLI to create the workspace, and take care of the initial setup.

ng new fullstack --collection=@angular/bazel
cd fullstack

Then we'll continue by building our app, and keeping all the Bazel generated files.

ng build --leaveBazelFilesOnDisk

This initial setup was explained in a previous article. If you have questions about some of the terms used in this article, or why we need to do this please go to the first post in this series.

There are a couple of things I did that are not required, but affect my initial setup files.

I renamed the src folder to client, and because I'm using CSS only, I removed everything related to sass in my imports and rules.

My initial Bazel files and config files look like this. (I removed the comments for brevity)

WORKSPACE

workspace(
    name = "project",
    managed_directories = {"@npm": ["node_modules"]},
)

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")

RULES_NODEJS_VERSION = "0.34.0"
RULES_NODEJS_SHA256 = "7c4a690268be97c96f04d505224ec4cb1ae53c2c2b68be495c9bd2634296a5cd"
http_archive(
    name = "build_bazel_rules_nodejs",
    sha256 = RULES_NODEJS_SHA256,
    url = "https://github.com/bazelbuild/rules_nodejs/releases/download/%s/rules_nodejs-%s.tar.gz" % (RULES_NODEJS_VERSION, RULES_NODEJS_VERSION),
)

load("@build_bazel_rules_nodejs//:defs.bzl", "check_bazel_version", "node_repositories",
    "npm_install")
check_bazel_version(
    message = """
You no longer need to install Bazel on your machine.
Your project should have a dependency on the @bazel/bazel package which supplies it.
Try running `yarn bazel` instead.
    (If you did run that, check that you've got a fresh `yarn install`)

""",
    minimum_bazel_version = "0.27.0",
)

node_repositories(
    node_repositories = {
        "10.16.0-darwin_amd64": ("node-v10.16.0-darwin-x64.tar.gz", "node-v10.16.0-darwin-x64", "6c009df1b724026d84ae9a838c5b382662e30f6c5563a0995532f2bece39fa9c"),
        "10.16.0-linux_amd64": ("node-v10.16.0-linux-x64.tar.xz", "node-v10.16.0-linux-x64", "1827f5b99084740234de0c506f4dd2202a696ed60f76059696747c34339b9d48"),
        "10.16.0-windows_amd64": ("node-v10.16.0-win-x64.zip", "node-v10.16.0-win-x64", "aa22cb357f0fb54ccbc06b19b60e37eefea5d7dd9940912675d3ed988bf9a059"),
    },
    node_version = "10.16.0",
)

npm_install(
    name = "npm",
    package_json = "//:package.json",
    package_lock_json = "//:package-lock.json",
)

load("@npm//:install_bazel_dependencies.bzl", "install_bazel_dependencies")
install_bazel_dependencies()

load("@npm_bazel_protractor//:package.bzl", "npm_bazel_protractor_dependencies")
npm_bazel_protractor_dependencies()

load("@npm_bazel_karma//:package.bzl", "rules_karma_dependencies")
rules_karma_dependencies()

load("@io_bazel_rules_webtesting//web:repositories.bzl", "web_test_repositories")
web_test_repositories()

load("@npm_bazel_karma//:browser_repositories.bzl", "browser_repositories")
browser_repositories()

load("@npm_bazel_typescript//:index.bzl", "ts_setup_workspace")
ts_setup_workspace()

BUILD.bazel

package(default_visibility = ["//visibility:public"])

exports_files([
    "tsconfig.json",
])

client/BUILD.bazel

package(default_visibility = ["//visibility:public"])

load("@npm_angular_bazel//:index.bzl", "ng_module")
load("@npm_bazel_karma//:index.bzl", "ts_web_test_suite")
load("@build_bazel_rules_nodejs//:defs.bzl", "rollup_bundle", "history_server")
load("@build_bazel_rules_nodejs//internal/web_package:web_package.bzl", "web_package")
load("@npm_bazel_typescript//:index.bzl", "ts_devserver", "ts_library")


ng_module(
    name = "client",
    srcs = glob(
        include = ["**/*.ts"],
        exclude = [
            "**/*.spec.ts",
            "main.ts",
            "test.ts",
            "initialize_testbed.ts",
        ],
    ),
    assets = glob([
      "**/*.css",
      "**/*.html",
    ]),
    deps = [
        "@npm//@angular/core",
        "@npm//@angular/platform-browser",
        "@npm//@angular/router",
        "@npm//@types",
        "@npm//rxjs",
    ],
)

rollup_bundle(
    name = "bundle",
    entry_point = ":main.prod.ts",
    deps = [
        "//client",
        "@npm//@angular/router",
        "@npm//rxjs",
    ],
)

web_package(
    name = "prodapp",
    assets = [
        "@npm//:node_modules/zone.js/dist/zone.min.js",
        ":bundle.min.js",
        "styles.css",
    ],
    data = [
        "favicon.ico",
    ],
    index_html = "index.html",
)

history_server(
    name = "prodserver",
    data = [":prodapp"],
    templated_args = ["client/prodapp"],
)

filegroup(
    name = "rxjs_umd_modules",
    srcs = [
        "@npm//:node_modules/rxjs/bundles/rxjs.umd.js",
        ":rxjs_shims.js",
    ],
)

ts_devserver(
    name = "devserver",
    port = 4200,
    entry_module = "project/client/main.dev",
    serving_path = "/bundle.min.js",
    scripts = [
        "@npm//:node_modules/tslib/tslib.js",
        ":rxjs_umd_modules",
    ],
    static_files = [
        "@npm//:node_modules/zone.js/dist/zone.min.js",
        "styles.css",
    ],
    data = [
        "favicon.ico",
    ],
    index_html = "index.html",
    deps = [":client"],
)

ts_library(
    name = "test_lib",
    testonly = 1,
    srcs = glob(["**/*.spec.ts"]),
    deps = [
        ":client",
        "@npm//@angular/core",
        "@npm//@angular/router",
        "@npm//@types",
    ],
)

ts_library(
    name = "initialize_testbed",
    testonly = 1,
    srcs = [
        "initialize_testbed.ts",
    ],
    deps = [
        "@npm//@angular/core",
        "@npm//@angular/platform-browser-dynamic",
        "@npm//@types",
    ],
)

ts_web_test_suite(
    name = "test",
    srcs = [
        "@npm//:node_modules/tslib/tslib.js",
    ],
    runtime_deps = [
        ":initialize_testbed",
    ],
    bootstrap = [
        "@npm//:node_modules/zone.js/dist/zone-testing-bundle.js",
        "@npm//:node_modules/reflect-metadata/Reflect.js",
    ],
    browsers = [
        "@io_bazel_rules_webtesting//browsers:chromium-local",
    ],
    deps = [
        ":rxjs_umd_modules",
        ":test_lib",
        "@npm//karma-jasmine",
    ],
)

angular.json

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "version": 1,
  "newProjectRoot": "projects",
  "projects": {
    "fullstack": {
      "projectType": "application",
      "schematics": {},
      "root": "",
      "sourceRoot": "client",
      "prefix": "app",
      "architect": {
        "build": {
          "builder": "@angular/bazel:build",
          "options": {
            "targetLabel": "//client:prodapp",
            "bazelCommand": "build"
          },
          "configurations": {
            "production": {
              "targetLabel": "//client:prodapp"
            }
          }
        },
        "serve": {
          "builder": "@angular/bazel:build",
          "options": {
            "targetLabel": "//client:devserver",
            "bazelCommand": "run",
            "watch": true
          },
          "configurations": {
            "production": {
              "targetLabel": "//client:prodserver"
            }
          }
        },
        "extract-i18n": {
          "builder": "@angular-devkit/build-angular:extract-i18n",
          "options": {
            "browserTarget": "fullstack:build"
          }
        },
        "test": {
          "builder": "@angular/bazel:build",
          "options": {
            "bazelCommand": "test",
            "targetLabel": "//client:test"
          }
        },
        "lint": {
          "builder": "@angular-devkit/build-angular:tslint",
          "options": {
            "tsConfig": [
              "tsconfig.app.json",
              "tsconfig.spec.json",
              "e2e/tsconfig.json"
            ],
            "exclude": [
              "**/node_modules/**"
            ]
          }
        },
        "e2e": {
          "builder": "@angular/bazel:build",
          "options": {
            "bazelCommand": "test",
            "targetLabel": "//e2e:devserver_test"
          },
          "configurations": {
            "production": {
              "targetLabel": "//e2e:prodserver_test"
            }
          }
        }
      }
    }},
  "defaultProject": "fullstack"
}

Expect breaking changes while v1.0 is on its way. Imports and rules may change.

Let's test to ensure that everything is working.

ng serve

Now that our project is setup, let's add a server folder where our backend will live.

Folder structure/naming is not important at this point. Use whatever works for you.

I'll build the server with express, and test it with jasmine and supertest. I'll start by installing the required dependencies.

npm install express --save
npm install --save-dev @bazel/jasmine jasmine supertest

Notice that I installed the @bazel/jasmine package that will contain the required rules to run the tests.

We'll create a very basic express server with some dummy data to return. In this first iteration, I'll use Javascript only. We also need to add a BUILD.bazel file to make it an independent package for the build tool.

If we don't create a BUILD.bazel file inside the server directory, it will be part of the root package.

server/index.js

const app = require("./app");

const PORT = process.env.PORT || 3000;

app.listen(PORT, _ => {
  console.log(`server listening on port ${PORT}`);
});

app.js

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

const { users } = require("./data");

// dev only
app.use((req, res, next) => {
  res.header("Access-Control-Allow-Origin", "*");
  next();
});

app.get('/', (req, res) => {
  res.json({ success: true });
});

app.get('/users', (req, res) => {
  res.json(users);
});

app.get('/users/:id', (req, res) => {
  const id = req.params.id;
  const user = users.find(u => u.id === parseInt(id, 10));
  if (!user) {
    return res.status(404).send('UserNotFound');
  }
  res.json(user);
});

module.exports = app;

data.js

const users = [
  { id: 1, name: "Greg", lastName: "Williams" },
  { id: 2, name: "Ann", lastName: "Roberts" }
];

module.exports = { users };

app.spec.js

const request = require("supertest");

const app = require("./app");
const { users } = require("./data");

it("should return all users", done => {
  request(app)
    .get("/users")
    .expect(200, users)
    .end((err, res) => {
      if (err) return done.fail(err);
      done();
    });
});

it("should return single user", done => {
  request(app)
    .get("/users/1")
    .expect(200, users[0])
    .end((err, res) => {
      if (err) return done.fail(err);
      done();
    });
});

it("should fail if a user with the given id is not found", done => {
  request(app)
    .get("/users/4")
    .expect(404)
    .expect(res => res.error.text === "UserNotFound")
    .end((err, res) => {
      if (err) return done.fail(err);
      done();
    });
});

server/BUILD.bazel

package(default_visibility = ["//visibility:public"])

load("@build_bazel_rules_nodejs//:defs.bzl", "nodejs_binary")
load("@npm_bazel_jasmine//:index.bzl", "jasmine_node_test")

nodejs_binary(
    name = "server",
    entry_point = "index.js",
    node_modules = "@npm//:node_modules",
    data = [
        "index.js",
        "app.js",
    ]
)

jasmine_node_test(
    name = "test",
    srcs = glob(["*.spec.js"]),
    deps = [ "//server"], 
    data = [ "data.js"], 
    node_modules = "@npm//:node_modules",
)

Now that our server is set up, how do we run tests, or start it? In the previous tutorial, we made use of the Angular CLI commands to take care of it, but in our server, this is not possible.

We'll use the @bazel/bazel and @bazel/ibazel dependencies for this purpose.
The only difference between bazel and ibazel is that the latter is running in "watch" mode. It will track any changes, and will restart whatever task it's doing.

To use the locally installed npm packages, we can create a script in package.json, or we can use the whole path to the executable files.

To run the server in watch mode:

./node_modules/.bin/ibazel run //server

We can run the server tests using a similar command.

./node_modules/.bin/ibazel test //server:test

The ibazel test command accepts multiple rules or packages to test. This makes it valid to run the server and client tests in a single command.

./node_modules/.bin/ibazel test //server:test //client:test

If we make a change in the server, the client tests will keep the cached version, because there's no server dependency declared. The same rule applies if we make changes on the client.

One of the benefits of keeping the server and the client together is the possibility to share information between them. It's hard to keep track of changes made to the server responses in the front end, even if we create an interface in our client code. We won't know of a breaking change until e2e tests fail (or someone lets us know that we must update our code).

Let's see how we can benefit from sharing types. We'll update our server to use TypeScript. We don't have to change everything at once. We can add a rule that transpiles a section of our code and the output becomes an input of the js rule we had before. We are sharing dependencies with our Angular project so TypeScript is already there.

server/BUILD.bazel

package(default_visibility = ["//visibility:public"])

load("@build_bazel_rules_nodejs//:defs.bzl", "nodejs_binary")
load("@npm_bazel_jasmine//:index.bzl", "jasmine_node_test")
load("@npm_bazel_typescript//:index.bzl", "ts_library")



ts_library(
    name = "app",
    srcs = ["app.ts", "data.ts"],
    deps = [
        "//models",
        "@npm//:node_modules",
        "@npm//@types",
    ],
)

nodejs_binary(
    name = "server",
    entry_point = "index.js",
    node_modules = "@npm//:node_modules",
    data = [
        "index.js",
        ":app",
    ]
)

jasmine_node_test(
    name = "test",
    srcs = glob(["*.spec.js"]),
    deps = [ "//server"], 
    node_modules = "@npm//:node_modules",
)

server/data.ts

import { User } from '../models/user';

export const users: User[] = [
  { id: 1, name: 'Greg', lastName: 'Williams' },
  { id: 2, name: 'Ann', lastName: 'Roberts' },
];

server/app.ts

import express = require('express');
const app = express();

import { users } from './data';

// dev only
app.use((req, res, next) => {
  res.header('Access-Control-Allow-Origin', '*');
  next();
});

app.get('/', (req, res) => {
  res.json({ success: true });
});

app.get('/users', (req, res) => {
  res.json(users);
});

app.get('/users/:id', (req, res) => {
  const id = req.params.id;
  const user = users.find(u => u.id === parseInt(id, 10));
  if (!user) {
    return res.status(404).send('UserNotFound');
  }
  res.json(user);
});

module.exports = app;

We partially migrated our code to typescript, and it still works. You may have noticed a dependency on the //models package/rule.

This will be our shared types directory.

models/user.ts

export interface User {
    id: number;
    name: string;
    lastName: string;
}

models/BUILD.bazel

package(default_visibility = ["//visibility:public"])
load("@npm_bazel_typescript//:index.bzl", "ts_library")
ts_library(
    name = "models",
    srcs = ["user.ts"],
)

We will proceed now to connect our server with the Angular app. Let's create a service that gets the users, and then in our app component we will show them.

client/app/user.service.ts

import { Injectable } from '@angular/core';
import { HttpClient } from '@angular/common/http';
import { User } from '../../models/user';
import { Observable } from 'rxjs';

@Injectable({
  providedIn: 'root'
})
export class UserService {

  constructor(private http: HttpClient) { }

  getUsers(): Observable<User[]> {
    return this.http.get<User[]>('http://localhost:3000/users');
}

client/app/app.component.ts

import { Component, OnInit } from '@angular/core';
import { UserService } from './user.service';
import { User } from '../../models/user';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css'],
})
export class AppComponent implements OnInit {
  users: User[] = [];

  constructor(private userService: UserService) {}

  ngOnInit() {
    this.userService.getUsers().subscribe(users => {
      this.users = users;
    });
  }
}

client/app/app.component.html

<ul>
  <li *ngFor="let user of users">
    {{user.name}} {{user.lastName}}
  </li>
</ul>

If we start our server and our client now, our not-so-fancy app should display the users list returned from the server.

./node_modules/.bin/ibazel run //server
./node_modules/.bin/ibazel run //client

If we decided to make a change on the User interface while working in the backend, it will immediately trigger a static analysis error on the front end. Let's assume we decided to change the name property to firstName.
We would have to change our server/data.ts to match the new interface. However, if we tried to build the client app, it would fail because types will not match.

Going forward

This was a very simple example (One server, one app). But as soon as your app starts growing, you may find yourself using different languages or creating libraries that are used by your application. Maybe you'll have multiple apps using the same server.

With the backend and the frontend being orchestrated by Bazel, you can have a common way of managing everything. You can also start splitting packages into smaller packages that can have their own set of tests, or that can be bundled separately, and have cached artifacts that can be reused, making your builds and tests faster.

We worked on full-stack development with Bazel using JS and/or TS. But this is just the tip of the iceberg. If your backend is not written in any of these languages, you may install Bazel using these instructions. It uses the same commands we've seen so far.

You can also share type information between languages using Protocol Buffers. Types will be autogenerated for each language using Bazel (of course!) and the Protocol Buffer Rules. These autogenerated types can now be declared as dependencies of your client and server.

Expect changes to come until v1 is here. Meanwhile, keep experimenting with Bazel.

References

Angular + Bazel: Getting ready!

Ignacio Le Fluk — Thu, 26 Sep 2019 20:45:44 +0000

In this post, I'll make an introduction to what is Bazel, how to use it with the Angular CLI and why it's a good idea to adopt it.

What is Bazel?

Bazel is a build tool/system with multi-language capabilities developed by Google.
It's extensible, meaning that you can add support for other languages and frameworks.
It also knows what and when to rebuild specific parts of your code and caches your build artifacts, making it very fast.

Concepts

Workspace: A workspace is the root directory that contains the source files to build. It should have at least a text file named WORKSPACE in it. If a WORKSPACE file is found in any sub-directory, it will be ignored by the parent workspace, creating a new workspace.

Package: Similar to workspaces, packages are directories beneath a workspace defined by a BUILD (or BUILD.bazel) file. If a subdirectory of a Package contains a BUILD file it's considered a different Package.

Targets: The elements of a Package are mainly of two types:

Files that can be generated by the build or source files provided by us.
Rules that given an input (source or generated files) will return an output (generated files). Rules outputs always belong to the same package of the rule.

Referencing

There are multiple ways of referencing files and outputs.
If you want to reference a Rule inside the same package you'll do it by using a colon (:) and the name of the rule.

a_rule(
    name = "rule_name"
)

another_rule(
    name = another_rule_name,
    deps = [
        ":rule_name"
    ]
)

When referencing another package we will use a double slash (//) to get to the root of the workspace and from there get to the desired package.

another_package_rule(
    name = "some_name",
    deps = [
        "//foo/bar:a_rule"
    ]
)

If the name of the rule matches the package name, then the rule name after the colon can be omitted.

A reference to //foo/bar:bar equals //foo/bar.

Bazel and Angular

Bazel is language and framework agnostic, but I would like to start by taking a look at how it can be used with Angular and understand what's happening.
Let's install the required dependencies and start a new project.

npm install -g @angular/bazel
ng new --collection=@angular/bazel

This command will create a new project with Bazel already set up as the build tool.

If we serve our app (ng serve) in our new project some new files will be created.

/WORKSPACE
/BUILD.bazel
.bazelignore
.bazelrc
/src/BUILD.bazel
/e2e/BUILD.bazel

We can for sure tell that the CLI defined a workspace, and three packages. Following the Package definition, the package located at the root will contain everything in the workspace except from the src and e2e folders.
If we stop our server, the files will be removed again.
That was zero-config Bazel!

But what can we do if we need to tweak our build because we installed a new library or because we want to optimize our build. We could create the WORKSPACE and BUILD files manually or we can use the --leaveBazelFilesOnDisk flag so the generated files are not removed.

ng build --leaveBazelFilesOnDisk

After we finish building we'll be able to explore and/or modify the generated files.

Let's start with /src/BUILD.bazel. I'll split the file in sections to explain them easily.

package(default_visibility = ["//visibility:public"])

At the very top, we have the visibility attribute. The visibility attribute will give access or not to the rules in this package from another package. Scopes of visibility can be set. For this example, we'll leave it as public.

load("@npm_angular_bazel//:index.bzl", "ng_module")
load("@npm_bazel_karma//:index.bzl", "ts_web_test_suite")
load("@build_bazel_rules_nodejs//:defs.bzl", "rollup_bundle", "history_server")
load("@build_bazel_rules_nodejs//internal/web_package:web_package.bzl", "web_package")
load("@npm_bazel_typescript//:index.bzl", "ts_devserver", "ts_library")
load("@io_bazel_rules_sass//:defs.bzl", "multi_sass_binary", "sass_binary")

Then all the imports that we'll be using with the load command. This will import a symbol from an extension.

After that, the rest is rules and its configurations.

sass_binary(
  name = "global_stylesheet",
  src = glob(["styles.css", "styles.scss"])[0],
  output_name = "global_stylesheet.css",
)


multi_sass_binary(
    name = "styles",
    srcs = glob(
      include = ["**/*.scss"],
      exclude = ["styles.scss"],
    ),
)

At the start of every rule, there's its name. This will let us reference it from other places and for example, including it as a dependency to another rule.

The first rule is named global_stylesheet, this means we can get a reference to its output by calling :global_stylesheet (from the same package). The source is either a .css or .scss file depending on our configuration. We also configure the output file.

Our second rule, styles, will transform all the .scss files, excluding the global style file.

If you (like me), prefer to use CSS we can get rid of many of this stuff. We'll do that in a moment.

Let's continue with the next rule. ng_module.

ng_module(
    name = "src",
    srcs = glob(
        include = ["**/*.ts"],
        exclude = [
            "**/*.spec.ts",
            "main.ts",
            "test.ts",
            "initialize_testbed.ts",
        ],
    ),
    assets = glob([
      "**/*.css",
      "**/*.html",
    ]) + ([":styles"] if len(glob(["**/*.scss"])) else []),
    deps = [
        "@npm//@angular/core",
        "@npm//@angular/platform-browser",
        "@npm//@angular/router",
        "@npm//@types",
        "@npm//rxjs",
    ],
)

First of all, we are naming the rule the same as the directory, this makes it easier later when referencing it. Naming your main rule the same as your package directory is a good practice. We are setting our sources (all .ts files, ignoring what is not part of the module), and our assets (.css and .html files, concatenated with the output of the styles rule that converts .scss files). Finally, we declare our dependencies, in this case, located in the npm workspace.

rollup_bundle(
    name = "bundle",
    entry_point = ":main.prod.ts",
    deps = [
        "//src",
        "@npm//@angular/router",
        "@npm//rxjs",
    ],
)

web_package(
    name = "prodapp",
    assets = [
        # do not sort
        "@npm//:node_modules/zone.js/dist/zone.min.js",
        ":bundle.min.js",
        ":global_stylesheet",
    ],
    data = [
        "favicon.ico",
    ],
    index_html = "index.html",
)

history_server(
    name = "prodserver",
    data = [":prodapp"],
    templated_args = ["src/prodapp"],
)

filegroup(
    name = "rxjs_umd_modules",
    srcs = [
        # do not sort
        "@npm//:node_modules/rxjs/bundles/rxjs.umd.js",
        ":rxjs_shims.js",
    ],
)

ts_devserver(
    name = "devserver",
    port = 4200,
    entry_module = "project/src/main.dev",
    serving_path = "/bundle.min.js",
    scripts = [
        "@npm//:node_modules/tslib/tslib.js",
        ":rxjs_umd_modules",
    ],
    static_files = [
        "@npm//:node_modules/zone.js/dist/zone.min.js",
        ":global_stylesheet",
    ],
    data = [
        "favicon.ico",
    ],
    index_html = "index.html",
    deps = [":src"],
)

ts_library(
    name = "test_lib",
    testonly = 1,
    srcs = glob(["**/*.spec.ts"]),
    deps = [
        ":src",
        "@npm//@angular/core",
        "@npm//@angular/router",
        "@npm//@types",
    ],
)

ts_library(
    name = "initialize_testbed",
    testonly = 1,
    srcs = [
        "initialize_testbed.ts",
    ],
    deps = [
        "@npm//@angular/core",
        "@npm//@angular/platform-browser-dynamic",
        "@npm//@types",
    ],
)

ts_web_test_suite(
    name = "test",
    srcs = [
        "@npm//:node_modules/tslib/tslib.js",
    ],
    runtime_deps = [
        ":initialize_testbed",
    ],
    # do not sort
    bootstrap = [
        "@npm//:node_modules/zone.js/dist/zone-testing-bundle.js",
        "@npm//:node_modules/reflect-metadata/Reflect.js",
    ],
    browsers = [
        "@io_bazel_rules_webtesting//browsers:chromium-local",
    ],
    deps = [
        ":rxjs_umd_modules",
        ":test_lib",
        "@npm//karma-jasmine",
    ],
)

The last section will setup and configure our bundler, the development server, the production build, and the tests.

When using Bazel, every dependency is declared, inputs and outputs are known. This will allow us to analyze what's going on and build a directed graph. We can query any package, rule or repository and its dependencies using the query command. The query command is very expressive in what you can request, and you can also get different output types. I recommend taking a look at the documentation. We'll be also using a tool to convert the query graph results to an image.

// get al the packages in the workspace
bazel query --output=graph ... | dot -Tpng > graph.png

This looks a little too much information. Fortunately, we can select portions of our graph.

bazel query "kind(rule, allpaths(//src:devserver, //...))" --output=graph | dot -Tpng > devserver.png

Let's start optimizing, and customizing our build, with what we have now. First of all, for this project, I decided that I won't be using any .scss file, so I can get rid of the styles rule. Remember to remove any reference to it as well.

I also want the app directory to be its own package, so I'll create a BUILD.bazel file in it.

package(default_visibility = ["//visibility:public"])

load("@npm_angular_bazel//:index.bzl", "ng_module")

ng_module(
    name = "app",
    srcs = glob(
        include = ["**/*.ts"],
        exclude = ["**/*.spec.ts"],
    ),
    assets = glob([
      "**/*.css",
      "**/*.html",
    ]),
    deps = [
        "@npm//@angular/core",
        "@npm//@angular/platform-browser",
        "@npm//@angular/router",
        "@npm//@types",
        "@npm//rxjs",
    ],
)

ts_library(
    name = "test_lib",
    testonly = 1,
    srcs = ["app.component.spec.ts"],
    deps = [
        ":app",
        "@npm//@angular/core",
        "@npm//@angular/router",
        "@npm//@types",
    ],
)

We've declared a new rule inside this new package inside src/app named app. We've also created a rule to handle the tests inside this package.
Next, we've removed the references to the styles rule, removed it, and instead we're setting the styles.css as the source. Also, we added a reference to the tests inside the app package.

ng_module(
    name = "src",
    srcs = glob(
        include = ["**/*.ts"],
        exclude = [
            "**/*.spec.ts",
            "main.ts",
            "test.ts",
            "initialize_testbed.ts",
        ],
    ),
    assets = glob([
      "**/*.css",
      "**/*.html",
    ]),
    deps = [
        "@npm//@angular/core",
        "@npm//@angular/platform-browser",
        "@npm//@angular/router",
        "@npm//@types",
        "@npm//rxjs",
        "//src/app"
    ],
)

rollup_bundle(
    name = "bundle",
    entry_point = ":main.prod.ts",
    deps = [
        "//src",
        "@npm//@angular/router",
        "@npm//rxjs",
    ],
)

web_package(
    name = "prodapp",
    assets = [
        # do not sort
        "@npm//:node_modules/zone.js/dist/zone.min.js",
        ":bundle.min.js",
        "styles.css",
    ],
    data = [
        "favicon.ico",
    ],
    index_html = "index.html",
)

history_server(
    name = "prodserver",
    data = [":prodapp"],
    templated_args = ["src/prodapp"],
)

filegroup(
    name = "rxjs_umd_modules",
    srcs = [
        # do not sort
        "@npm//:node_modules/rxjs/bundles/rxjs.umd.js",
        ":rxjs_shims.js",
    ],
)

ts_devserver(
    name = "devserver",
    port = 4200,
    entry_module = "project/src/main.dev",
    serving_path = "/bundle.min.js",
    scripts = [
        "@npm//:node_modules/tslib/tslib.js",
        ":rxjs_umd_modules",
    ],
    static_files = [
        "@npm//:node_modules/zone.js/dist/zone.min.js",
        "styles.css",
    ],
    data = [
        "favicon.ico",
    ],
    index_html = "index.html",
    deps = [":src"],
)

ts_library(
    name = "test_lib",
    testonly = 1,
    srcs = glob(["**/*.spec.ts"]),
    deps = [
        ":src",
        "@npm//@angular/core",
        "@npm//@angular/router",
        "@npm//@types",
    ],
)

ts_library(
    name = "initialize_testbed",
    testonly = 1,
    srcs = [
        "initialize_testbed.ts",
    ],
    deps = [
        "@npm//@angular/core",
        "@npm//@angular/platform-browser-dynamic",
        "@npm//@types",
    ],
)

ts_web_test_suite(
    name = "test",
    srcs = [
        "@npm//:node_modules/tslib/tslib.js",
    ],
    runtime_deps = [
        ":initialize_testbed",
    ],
    # do not sort
    bootstrap = [
        "@npm//:node_modules/zone.js/dist/zone-testing-bundle.js",
        "@npm//:node_modules/reflect-metadata/Reflect.js",
    ],
    browsers = [
        "@io_bazel_rules_webtesting//browsers:chromium-local",
    ]`
    deps = [
        ":rxjs_umd_modules",
        ":test_lib",
        "//src/app:test_lib",
        "@npm//karma-jasmine",
    ],
)

If we analyze our dev server again.

I believe most of the benefits when using Bazel start to be more evident once your workspace starts growing. The pattern becomes roughly the same for each module you start adding.
Here's an example where I added a core module, and a shared module used by other 2 modules (users, repositories). You can easily start exploring the tree of dependencies.

Because Bazel is always AOT, be aware that when lazy loading a module, we must use the factory module.
For example:

const routes: Routes = [
  {
    path: 'users',
    loadChildren: () => import('./users/users.ngfactory').then(m => m.UsersModuleNgFactory)
  },
  {
    path: 'repositories',
    loadChildren: () =>
        import('./repositories/repositories.module.ngfactory').then(m => m.RepositoriesModuleNgFactory)
  }
]

If you look closely at the main.dev.ts and main.prod.ts we're also bootstrapping the factory module.

platformBrowser().bootstrapModuleFactory(AppModuleNgFactory);

Now that we have an idea on how to work with Bazel, let's talk about its benefits.
I think most of them will shine on large codebases with lots of tests. Fortunately, it's adoption can be incremental (One package that does everything) and you can start creating more specific packages and begin declaring it's dependencies.

You can make use also of remote build and caching. Because for a given set of inputs, the output is always the same, you can cache the results and share it. If your CI already run the tests, when you make changes locally you can use the cached results of the unaffected tests and run only the affected ones. The same goes for the builds, reducing build times.

We've started only with an Angular application, but Bazel allows to do a lot more and because it's language agnostic, you can start referencing also the backend (perhaps written in another language), and use Bazel as the build tool.

Even though Bazel extensible, there's been a lot of work on making the needed rules already available. So there might be a low chance of needing to write a custom one. In case you're wondering on how to do it, Rules are written using Starlark a dialect of Python.

Some of the features presented here are still part of Angular Labs and might change in the future.

References

Enjoy this article? Head on over to This Dot Labs and check us out! We are a tech consultancy that does all things javascript and front end. We specialize in open source software like, Angular, React and Vue.

Schematics: Bloques de construcción

Ignacio Le Fluk — Thu, 05 Sep 2019 23:41:57 +0000

Introducción

Una de las herramientas más poderosas que el ecosistema Angular nos provee como desarrolladores es su CLI. ¿Alguna vez se han preguntado como es que los componentes, servicios y otros se crean cada vez que corremos el comando ng generate?
La línea de comandos hace uso por detrás de Schematics, específicamente la colección de schematics por defecto: @schematics/angular.
En este post, exploraremos algunos conceptos clave cuando trabajamos con schematics, entenderemos sus operaciones básicas y construiremos nuestra propia colección de schematics desde cero usando su propio CLI.

El Tree

Schematics nos permite operar en un sistema de archivos virtual, llamado Tree. Cuando ejecutemos un schematic podremos preparar una serie de transformaciones a èl (Crear, actualizar o eliminar archivos), y finalmente aplicar (o no) esos cambios.

Creando nuestro primer schematic

Para crear nuestro primer schematic, comenzaros por instalar el CLI de Schematics , el cual nos ayudará a construir nuestra colección.

// instalar CLI
npm install -g @angular-devkit/schematics-cli

//crear colección
schematics blank my-collection // or schematics blank --name=my-collection

El comando schematics funciona de dos maneras dependiendo de dónde es usado.
Si no estamos en un directorio de un projecto de schematics, creará uno nuevo con la estructura básica e instalará sus dependencias, en caso contrario, añadirá un nuevo schematic a la colección.

Demos una mirada a la estructura de proyecto.

collection.json contiene la información de nuestra colección, expone los schematics que contendrá y los enlaza con los métodos apropiados. Hay más configuración que se puede realizar en este archivo, como añadir un alias, pero eso lo veremos más adelante.

{
  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "my-collection": {
      "description": "A blank schematic.",
      "factory": "./my-collection/index#myCollection"
    }
  }
}

El schematic por defecto cuando se crea una nueva colección tendrá el mismo nombre que la colección. Un schematic debe exportar al menos una función que nos retorne una regla, de tipo Rule. Nuestro nuevo schematic tiene una pequeña descripción, y una ruta al archivo que lo contiene, seguido del nombre de la función que usará cuando sea llamado.

// src/my-collection/index.ts
import { Rule, SchematicContext, Tree } from "@angular-devkit/schematics";

export function myCollection(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    return tree;
  };
}

index.ts exporta una única función, una función que nos retorna una regla (Rule). Rule es una función que dados un Tree y un contexto (SchematicContext), nos retornará un nuevo Tree
En el ejemplo anterior, ninguna transformación fue aplicada.

Puedes exportar más de una función de un sólo archivo. También puedes elegir exportar una funciòn default y omitir la última parte del path al método en collection.json.

Build y ejecución

Antes de poder ejecutar nuestro schematic tenemos que crear un nuevo build de nuestra colección. Para esto utilizaremos dos comandos:

// build
npm run build

// ejecutar
schematics .:my-collection

Primero, construimos nuestra colección usando npm run build y luego los ejecutamos usando el CLI de schematics. Le indicamos al CLI que ejecute el schematic my-coleccion en el directorio de la colección actual(schematics \<ruta\>:\<nombre-schematic\>).

Recuerda ejecutar un build de tu colección antes de testearla. Mi recomendación es ejecutar el comando con el flag watch mientras desarrollamos.(npm run build -- --watch)

Logs

Hasta el momento nuestro schematic no hace nada. Mostrar información en pantalla puede entregar información valiosa al usuario o ayudarnos mientras depuramos nuestra colleción (debug). Cambiemos nuestro schematic para que muestre información.

// src/my-collection/index.ts
export function myCollection(_options: any): Rule {
  return (tree: Tree, context: SchematicContext) => {
    context.logger.info('Info message');
    context.logger.warn('Warn message');
    context.logger.error('Error message');

    return tree;
  };
}

Si corremos nuestro schematic ahora(recuerda hacer un build antes), podremos ver nuestros mensajes coloreados según el tipo de log.

Creando archivos

Ahora que sabemos como imprimir información en pantalla, podemos comenzar a modificar nuestro tree. Comenzaremos por crear un nuevo schematic que añadirá un nuevo archivo.

schematics blank create-file

Nuestro nuevo schematic fue añadido a la colección, notarás que un nuevo directorio fue creado y collection.json fue modificado para incluir este nuevo schematic. Podemos ahora editar nuestro método createFile para modificar nuestro tree.

// src/create-file/index.ts
import { Rule, SchematicContext, Tree } from "@angular-devkit/schematics";

export function createFile(_options: any): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    tree.create("test.ts", "File created from schematic!");
    return tree;
  };
}

Nuestra regla o Rule tomará nuestro tree, añadirá un archivo llamado test.ts en la raíz de éste, y retornará este nuevo tree modificado.

Corremos el Build y ejecutamos.

schematics .:create-file

¿Éxito? Si miramos dentro de nuestro de nuestro directorio no seremos capaces de encontrar el archivo supuestamente creado. Eso es porque nuestro schematic correrá en modo debug cuando es llamado desde una ruta relativa. Esto significa que no hará modificaciones reales al sistema de archivos. Para aplicar los cambios, debemos agregar la opción --debug=false al comando. Si lo intentamos nuevamente, test.js será finalmente creado con el contenido deseado en él. Elimina el archivo antes de continuar.

Si ejecutamos el comando nuevamente, fallará porque create no sobreescribirá un archivo que ya existe.

Argumentos y schemas

Nuestro schematic es muy limitado hasta el momento. Siempre creará el mismo archivo sin importar lo que hagamos. ¿No sería mejor si pudieramos pasar ciertos argumentos? Para lograr esto definiremos un schema. Creemos un archivo llamado schema.json dentro de la carpeta create-file. También crearemos una interfaz en schema.ts que equivalga a los argumentos declarados en el archivo .json

{
  "$schema": "http://json-schema.org/schema",
  "id": "my-collection-create-file",
  "title": "Creates a file using the given path",
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "The path of the file to create."
    }
  },
  "required": ["path"]
}

// src/create-file/schema.ts
export interface CreateFileOptions{
  path:string;
}

Declaramos un nuevo argumento llamado path y lo marcamos como required (requerido) en schema.json.

Agreguemos el schema y la interfaz a nuestra función y al schema de la colección.

import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
import { CreateFileOptions } from './schema';

export function createFile(options: CreateFileOptions): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    tree.create(options.path, "File created from schematic!");
    return tree;
  };
}

{
  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "my-collection": {
      "description": "A blank schematic.",
      "factory": "./my-collection/index#myCollection"
    },
    "create-file": {
      "description": "A blank schematic.",
      "factory": "./create-file/index#createFile",
      "schema": "./create-file/schema.json"
    }
  }
}

Al crear una interfaz hemos agregado inferencia de tipo al argumento options de nuestra función. La propiedad schema debe ser agregada a la declaracion del schematic en collection.json con la ruta al archivo del schema.
Este schema hará que el CLI falle en caso de que el argumento path nos es indicado.

Hacemos un build y ejecutamos.

schematics .:create-file

Si ejecutamos el schematic sin el argumento path, fallará.

Ejecutémoslo nuevamente pasando un argumento.

schematics .:create-file --path=test-path.ts

Aunque el schema y la interfaz no son requeridas, nos proveen de validacion y type checking. El comando ng generate leerá este schema y nos mostrarà los argumentos disponibles cuando lo ejecutemos con el flag --help.

Consultando al usuario y alias

Puede ser difícil recordar todos los argumentos que un schematic puede recibir. Podemos hacer nuestro schematic más amigable con el usuario preguntándole por los argumentos requeridos. Por otro lado, podemos hacer nuestros comandos mas cortos o legibles añadiéndole un alias a nuestro schematic. Esto lo haremos modificando algunas proiedades de nuestro schema.

Primero, añadiremos la entrada x-prompt a la propiedad que lo requiere en schema.json. El usuario será consultado si el argumento no se provee.

{
  "$schema": "http://json-schema.org/schema",
  "id": "my-collection-create-file",
  "title": "Creates a file using the given path",
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "The path of the file to create.",
      "x-prompt": "Enter the file path:",
    }
  },
  "required": ["path"]
}

Para crear un alias, agregaremos la propiedad aliases al schematic en el archivo collection.json.

{
  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "my-collection": {
      "description": "A blank schematic.",
      "factory": "./my-collection/index#myCollection"
    },
    "create-file": {
      "description": "A blank schematic.",
      "factory": "./create-file/index#createFile",
      "schema": "./create-file/schema.json",
      "aliases": ["cf"]
    }
  }
}

Ahora podemos ejecutar nuestro schemtic usando el alias cf y si llegamos a olvidarnos del argumento path, se nos requerirá por el CLI.

schematics .:cf

Templates

Pasar un argumento para cambiar el archivo está bien, pero nuestro contenido es siempre el mismo. Pasar el contenido como un argumento no sería práctico ya que podría ser complejo. Afortunadamente, podemos crear templates cuando tengamos que lidiar con este tipo de contenido. Los templates no son mas que archivos o plantillas que pueden ser copiads, movidos y modificados en nuestro tree.

Creemos un nuevo schematic aplicando los conceptos que hemos visto anteriormente.

schematics blank create-from-template

collection.json (partial)

{
  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": { 
    "create-from-template": {
      "description": "A blank schematic.",
      "factory": "./create-from-template/index#createFromTemplate",
      "schema": "./create-from-template/schema.json",
      "aliases": ["cft"]
    }
  }
}

// src/create-from-template/schema.ts
export interface CreateFromTemplateOptions {
  folder: string;
}

// src/create-from-template/schema.json
{
  "$schema": "http://json-schema.org/schema",
  "id": "my-collection-create-from-template",
  "title": "Creates files in the given folder",
  "type": "object",
  "properties": {
    "folder": {
      "type": "string",
      "description": "The destination folder of the files to create.",
      "x-prompt":"Enter the destination folder:"
    }
  },
  "required": ["folder"]
}

Para crear los templates, haremos un directorio /files dentro de la carpeta del schematic y ubicaremos los archivos que seran copiados.

Puedes usar cualquier nombre de carpeta, mientras sea ignorado por el compilador. /files es ignorado por defecto.

Hemos añadido dos archivos dentro de nuestra carpeta. Ahora podremos hacer uso de ellos dentro de nuestro schematic.

// src/create-from-template/index.ts
import {
  Rule,
  SchematicContext,
  Tree,
  Source,
  url,
  mergeWith,
  move,
  apply
} from "@angular-devkit/schematics";
import { CreateFromTemplateOptions } from "./schema";
import { normalize } from "@angular-devkit/core";

export function createFromTemplate(options: CreateFromTemplateOptions): Rule {
  return (tree: Tree, context: SchematicContext) => {
    const source: Source = url("./files");
    const transformedSource: Source = apply(source, [
      move(normalize(options.folder))
    ]);

    return mergeWith(transformedSource)(tree, context);
  };
}

Hay varias cosas ocurriendo aquí. Primero, estamos leyendo desde el directorio de nuestros templates usando la funcion url que retornará un Source. Luego aplicamos una serie de reglas a cada uno de los archivos de origen. En este ejemplo estamos moviendo los archivos desde la raìz hasta la carpeta dada como argumento. Finalmente, unimos la fuente modificada con nuestro tree original.

Build y ejecutamos.

Nuestros archivos fueron copiados desde el directorio /files de nuestro schematic a /my-folder en nuestro proyecto.

Contenido dinámico

Tomemos un paso hacia a atrás y pensemos en ejemplos reales de schematics. Cuando creamos un componente usando el CLI de Angular, un grupo de archivos y un directorio son creados. Esos archivos cambian su nombre y contenido dependiendo del input del usuario. ¿Cómo podemos conseguir algo similar?
Haremos uso de la función template que nos provee angular-devkit/schematics y la aplicaremos a nuestros archivos fuente.

// ...imports
export function createFromTemplate(options: CreateFromTemplateOptions): Rule {
  return (tree: Tree, context: SchematicContext) => {
// ...
    const transformedSource: Source = apply(source, [
      template({
        filaname: options.folder,
        ...strings // dasherize, classify, camelize, etc
      }),
      move(normalize(folder))
    ]);

    return mergeWith(transformedSource)(tree, context);
  };
}

template tomará un objeto como argumento y permitirá que todas sus propiedades esten disponibles para ser utilizadas por los nombres de archivos y sus contenidos. En este caso estamos pasándole un objecto con el nombre de directorio sin formatear y un set de métodos para transformar strings.
Para probar su funcionamiento crearemos dos archivos.

// files/__filename@dasherize__.ts
export class <%= classify(filename) %> {
    constructor(){}
}

<!-- files/__filename@dasherize__.html -->
<ul>
  <li><%= dasherize(filename) %></li>
  <li><%= camelize(filename) %></li>
  <li><%= capitalize(filename) %></li>
  <li><%= underscore(filename) %></li>
</ul>

¡Mira esos nombres de archivo!. __ es el delimitador de inicio y fin por defecto, @ pasará el argumento (antes del símbolo) a la función (despues del símbolo). En este ejemplo, el nombre de archivo será paasado como un argumento a la función dasherize y el valor retornado será seguido de la extension de archivo.

Dentro de nuestro templates, seguiremos usando la funciones para manipular strings y el nombre de archivo

Una vez más, hacemos un build y ejecutamos.

schematics .:cft --folder=very-complexFolder_name

Los nombres de archivo fueron formateados de la forma que queríamos (dasherized o separando palabras con guiones). Revisemos el contenido de los archivos. (Recuerda ejecutar el comado con la opcion --debug=false para poder verlos)

<!-- very-complex-flder-name.html -->
<ul>
  <li>very-complex-folder-name</li>
  <li>veryComplexFolderName</li>
  <li>Very-complexFolder_name</li>
  <li>very_complex_folder_name</li>
</ul

// very-complex-folder-name.ts
export class VeryComplexFolderName {
    constructor(){}
}

Nuestro schematic comienza a verse mucho más útil!

Eliminando archivos

Siguiente en la lista se encuentra eliminar archivos

Creemos un nuevo schematic.

schematics blank --name=remove-file

collection.json

{
  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "remove-file": {
      "description": "Removes a file",
      "factory": "./remove-file/index#removeFile",
      "schema": "./remove-file/schema.json",
      "aliases": ["rm"]
    }
  }
}

schema.json

{
  "$schema": "http://json-schema.org/schema",
  "id": "my-collection-remove-file",
  "title": "Deletes a file using the given path",
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "The path of the file to remove.",
      "x-prompt":"Enter the file path:"
    }
  },
  "required": ["path"]
}

// src/remove-file/schema.ts
export interface RemoveFileOptions {
  path: string;
}

// src/remove-file/index.ts
import { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
import { RemoveFileOptions } from './schema';

export function removeFile(options: RemoveFileOptions): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    tree.delete(options.path);
    return tree;
  };
}

Antes de correr el schematic asegúrate que el archivo a eliminar existe. Recuerda que por defecto estamos ejecutándo en modo debug así que los cambios no se aplicarán realmente.

schematics .:rm --path=src/collection.json

Actualizando archivos

Borrar archivos pareció mucho más simple que crearlos. Dejé la actualización de archivos para el último ya que (en mi opinión) involucra las operaciones más complejas, dependiendo del tipo de archivo y como estamos modificándolos. Puede ser tan simple como añadir unas cuantas líneas de código al inicio (o al final)de un archivo o tan complejo como haciendo uso del AST (abstract syntax tree) de Typescript para determinar donde y como ejecutar la actualización.

Creemos un nuevo schematic.

schematics blank overwrite-file

// src/overwrite-file
export function overwriteFile(options: OverwriteFileOptions): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    const buffer = tree.read(options.path);
    const content = buffer ? buffer.toString() : '';
    const comment = `// ¯\_(ツ)_/¯\n`;
    if(!content.includes(comment)){
      tree.overwrite(options.path, comment + content)
    }
    return tree;
  };
}

Omití la creación del schema y la actualizaciín de la colección ya que es similar a lo que hemos hecho con el resto.
Nuestra función lee un archivo desde la ruta dada por el usuario. Convierte ese buffer a un string, chequea si un comentario ya fue añadido al archivo y lo agrega al inicio del archivo si no está presente. Luego sobreescribimos el archivo con el contenido actualizado. Podrímaos hacer otro tipo de verificaoines para evitar, por ejemplo, agregar un comentario a un archivo .json, invalidándolo, pero esta fuera de alcance de este tutorial.

Esta no es la unica forma de actualizar un archivo.

schematics blank update-recorder

export function updateRecorder(options: RecorderOptions): Rule {
  return (tree: Tree, _context: SchematicContext) => {

    const comment = '// ᕙ(⇀‸↼‶)ᕗ\n';

    const updateRecorder: UpdateRecorder = tree.beginUpdate(options.path);

    updateRecorder.insertLeft(0, comment);
    updateRecorder.insertLeft(0, comment);
    updateRecorder.insertLeft(0, comment);
    updateRecorder.insertLeft(0, comment);

    tree.commitUpdate(updateRecorder);

    return tree;
  };
}

Esto es similar a lo que hicimos en el schematic anterior, pero funciona un poco diferente. Primero, leemos nuestro archivo y luego comenzamos a insertar valores (stringo Buffer) a la izquierda o derecha de una posición dada. Los cambios son aplicados al tree sólo después de llamar a la funcion commitUpdate.
La parte interesante es la posición para insertar los valores y cómo determinaremos dónde queremos hacer modificaciones. En este ejemplo, la posición no importa mucho ya que estamos insertando al inicio del contenido, pero ahora veremos un escenario más complejo. No olvidemos de hacer el build y ejecutar!

Usando el AST de Typescript

Digamos que queremos leer un archivo Typescript, deseamos encontrar la primera interfaz declarada en él y agregar una propiedad al principio y otra al final. Podríamos tratar de leer todo como texto y encontrar los caracteres apropiados o, mejor aún, podríamos usar el AST de Typescript para navegar nuestros archivos, sin pensar en caracteres, sino en nodos que tienen un significado.

schematics blank ts-ast

import { Rule, SchematicContext, Tree, SchematicsException } from '@angular-devkit/schematics';
import * as ts from 'typescript';

export function tsAst(options: TsAstOptions): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    const buffer = tree.read(options.path);
    if(!buffer){
      throw new SchematicsException(`File ${options.path} not found.`);
    } 

    const source = ts.createSourceFile(options.path, buffer.toString(), ts.ScriptTarget.Latest, true);
    const nodes = getSourceNodes(source);

    const interfaceDeclaration = nodes.find(n=>n.kind === ts.SyntaxKind.InterfaceDeclaration);
    if(!interfaceDeclaration){
      throw new SchematicsException(`No Interface found`);
    }

    const [openBrace, closeBrace] = [
      interfaceDeclaration!.getChildren().find(n=>n.kind===ts.SyntaxKind.OpenBraceToken),
      interfaceDeclaration!.getChildren().slice().reverse().find(n=>n.kind===ts.SyntaxKind.CloseBraceToken),
    ]

    const text = interfaceDeclaration!.getText();
    let indentation;
    const matches = text.match(/\r?\n\s*/);
    if (matches && matches.length > 0) {
      indentation = matches[0]
    } else {
      indentation= ''
    }

    const recorder = tree.beginUpdate(options.path);
    recorder.insertRight(openBrace!.end, `${indentation}first: string;`);
    recorder.insertLeft(closeBrace!.pos, `${indentation}last: string;`);
    tree.commitUpdate(recorder);
    return tree;
  };
}


// tomado de los schematics de angular. Retorna un array de Nodes
function getSourceNodes(sourceFile: ts.SourceFile): ts.Node[] {
  const nodes: ts.Node[] = [sourceFile];
  const result = [];

  while (nodes.length > 0) {
    const node = nodes.shift();

    if (node) {
      result.push(node);
      if (node.getChildCount(sourceFile) >= 0) {
        nodes.unshift(...node.getChildren());
      }
    }
  }

  return result;
}

Vayamos paso a paso a través de este archivo.
Primero nos aseguramos que el archivo existe. En caso contrario, arrojaremos un error. Luego, usando el compilador de typescript, leemos el archivo y obtenemos todos los nodos del AST. Luego buscaremos el primer nodo de tipo InterfaceDeclaration. La lista de tipos de nodods es muy extensa. Éste tipo en particular retornara la declaración completa de la interfaz hasta la llave de cierre. Con cada nodo, obtendremos la posición inicial y final. (¿Recuerdan los métodos insertLeft e insertRight?)
Aún no llegamos donde queremos llegar, podemos obtener más información de este nodo aislado. Comenzaremos por obtener todos sus nodos hijo, y buscaremos la primera ocurrencia de una llave de apertura ({) y la ultima llave de cierre (}). Estos nodos también contienen una posición de inicio y fin.

El espacio en blanco no tiene 'significado' en nuestro árbol sintáctico, así que tomaremos una estrategia diferente. Leeremos el texto de nuestra declaración de interfaz y obtendremos el epacio en blanco para poder determinar la indentación. Esto es sólo por motivos estéticos, ya que una nueva linea bastaría.

Ahora es momento de comenzar nuestra modificación, insertaremos a la derecha de nuestra llave de apertura y a la izquierda de nuestra llave de cierre. Recordemos que nada ha cambiado hasta que llamemos el método commitUpdate. Aunque hayamos insertado algo después de la llave inicial, la posición de la llave final sigue siendo la misma que antes, y podemos insertar con seguridad a la izquierda de ésta.

Crearemos un archivo de prueba y correremos nuestro schematic. (No olvidar el build))

interface TestInterface {
  aProperty: string;
}

Luego de correr nuestro schematic deberíamos obtener un archivo similar a este:

interface TestInterface {
  first:string;
  aProperty: string;
  last:string;
}

!Èxito!

Palabras finales

Aunque los schematics son ampliamente usados en el ecosistema de Angular, no están limitados a éste. De hecho, todos lo ejemplos que hemos hecho hasta ahora han sido usados fuera de un proyecto de Angular.
En la próxima parte de esta serie, aprenderemos acerca de las tareas (tasks) y cómo testear schematics, extenderlos y correrlos en secuencia.
En la parte 3, crearemos un ejemplo 'real' de una colección de schematics que añadirán TailwindCSS a un proyecto Angular.
Pueden encontrar el código final en este repositorio

Referencias

Artículos/Libros relacionados

El post original se encuentra aquí

Este artículo fue escrito por Ignacio Falk, software engineer en This Dot.

Pueden seguirlo en Twitter como @flakolefluk.

¿Necesita consultoría, mentores o entrenamiento en JavaScript? Revise nuestra lista de servicios en This Dot Labs.

Schematics: Add Tailwind CSS to your Angular project

Ignacio Le Fluk — Tue, 27 Aug 2019 20:06:35 +0000

This is part 3 of the series on Schematics.

TailwindCSS

I've been hearing a lot lately about Tailwind CSS and I wanted to give it a try. Tailwind is a PostCSS plugin, and adding it to an Angular project is not a trivial task. It involves a few steps.
Googling a little bit, I found a few examples of how to add it. Some options included using an extra CLI, or adding a script to run before building. But, I prefer to stick with what's already provided with the Angular CLI, and the possibilities to extend it.

This example will work with Angular 8 or higher.

We'll need to do a couple of things to get this working.

create webpack config files for dev and production builds.
create a tailwind configuration file.
update our global styles file and add tailwind styles
update angular.json to use a custom builder.
update package.json and add all required dependencies
install dependencies

This is a great opportunity to create a schematics collection, and automate this process.

Create a new schematics collection, remove unnecessary files, and create two schematics named ng-add and ng-add-setup

schematics blank --name=tailwind-schematics
cd tailwind-schematics
rm -rf src/tailwind-schematics
schematics blank --name=ng-add
schematics blank --name=ng-add-setup

Clean collection.json, and remove references to the deleted tailwind schematic.

{
  "$schema": "../node_modules/@angular-devkit/schematics/collection-schema.json",
  "schematics": {
    "ng-add": {
      "description": "Adds tailwindCSS to an Angular project",
      "factory": "./ng-add/index#ngAdd",
      "schema": "./ng-add/schema.json"
    },
    "ng-add-setup": {
      "description": "Setups project before installing dependencies",
      "factory": "./ng-add-setup/index#ngAddSetup",
      "private": true,
      "schema": "./ng-add-setup/schema.json"
    }
  }
}

Notice that ng-add-setup is marked as private. We listed it in our collection, because we want it to be accessible by the ng-add schematic.

We will split the list of actions into two tasks: the first task is to create, and update files, and another task is to install our dependencies.
ng-add will be in charge of running the tasks in order. We will also add a flag to determine if we should run the installation after the changes are made.
Remember to add a schema to your schematic.

{
  "$schema": "http://json-schema.org/schema",
  "id": "tailwind-ng-add-schematic",
  "title": "Add tailwind to angular project",
  "type": "object",
  "properties": {
    "project": {
      "type": "string",
      "description": "The name of the project."
    },
    "skipInstall": {
      "type": "boolean",
      "description": "Condition to run npm install"
    }
  },
  "required": [],
  "additionalProperties": false
}

export interface NgAddOptions {
  project: string;
  skipInstall: boolean;
}

export function ngAdd(options: NgAddOptions): Rule {
  return (tree: Tree, context: SchematicContext) => {
    // 1. Do some checks before starting
    const workspace = getWorkspace(tree);
    const packageJson = getPackageJson(tree);
    const projectName = options.project || workspace.defaultProject;

    const coreVersion: string = packageJson.dependencies['@angular/core'];

    if (!coreVersion) {
      throw new SchematicsException(
        'Could not find @angular/core version in package.json.',
      );
    }

    const majorVersion: number = parseInt(
      coreVersion.split('.')[0].replace(/\D/g, ''),
      10,
    );

    if (majorVersion < 8) {
      throw new SchematicsException('Minimum version requirement not met.');
    }

   // 2. run schematic that chain a set of schematics that will add and update files
    const setupId = context.addTask(
      new RunSchematicTask('ng-add-setup', { project: projectName }),
    );

   // 3. Install dependencies (or skip installation)
    if(!options.skipInstall){
      context.addTask(new NodePackageInstallTask(), [setupId]);
    }
  };
}

There a few utility functions that I'm using here to get, and parse angular.json and package.json. For version 0.0.1, we'll be supporting Angular 8+, and making sure that the project meets this requirement.
Then, we will run the ng-add-setup schematic, and after it finishes, we will optionally run the NodePackageInstall task.

Most of the work will be handled by ng-add-setup. Let's scaffold how it will work.

export interface NgAddSetupOptions {
  project: string;
}

export function ngAddSetup(options: NgAddSetupOptions): Rule {
    return chain([
      addWebpackConfigFiles(options),
      addTailwindConfigFile(options),
      updateStylesFile(options),
      updateAngularConfig(options),
      updatePackageJson(options),
    ])(tree, _context);
  };
}

function addWebpackConfigFiles(options): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    // ...create webpack config files (from template)
  }
}

function addTailwindConfigFile(options): Rule {
  return (tree: Tree, _context: SchematicContext) => {
   // ...create tailwind config files (from template)
  };
}

function updatePackageJson(options): Rule {
  return (tree: Tree, _context: SchematicContext): Tree => {
    // add dependencies and devdepencies to package.json
  };
}

function updateStylesFile(options): Rule {
  return (tree: Tree, _context: SchematicContext) => {
   // add @tailwind imports to global styles file
  };
}

function updateAngularConfig(options): Rule {
  return (tree: Tree, _context: SchematicContext) => {
   // modify angular.json to use custom webpack config and builders
  };
}

We will start with file creation. As we saw before, we'll create a folder with the files that will be added.

We'll name our files webpack.config.json, webpack-prod.config.json, and tailwind.config.js

I created these files inside their own folders webpack and tailwind. I prefer to keep it this way to make it easier later when reading these folders.

// files/webpack/webpack.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\<%= stylesExt %>$/,
        use: [
          {
            loader: "postcss-loader",
            options: {
              plugins: [
                require("tailwindcss")("./tailwind.config.js"),
                require("autoprefixer")
              ]
            }
          }
        ]
      }
    ]
  }
};

// files/webpack/webpack-prod.config.js
module.exports = {
  module: {
    rules: [
      {
        test: /\<%= stylesExt %>$/,
        use: [
          {
            loader: "postcss-loader",
            options: {
              plugins: [
                require("tailwindcss")("./tailwind.config.js"),
                require("@fullhuman/postcss-purgecss")({
                  content: [
                    "./src/**/*.component.html",
                    "./src/**/*.component.ts"
                  ],
                  defaultExtractor: content =>
                    content.match(/[A-Za-z0-9-_:/]+/g) || []
                }),
                require("autoprefixer")
              ]
            }
          }
        ]
      }
    ]
  }
};

We are passing the styles extension to our config template to let it know what files to look for.
Both config files look very similar, but on production, we will be running PurgeCSS to remove all the code that we are not using on our application. This is an important step to follow. If you don't, your CSS file will be huge.

// ...
function addWebpackConfigFiles(stylesExt: string, projectSrcRoot: string): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    const source: Source = url('files/webpack');
    return mergeWith(
      apply(source, [
        template({ stylesExt }),
        move(normalize(`${projectSrcRoot}/..`)),
      ]),
    )(tree, _context);
  };
}
// ...

Our function will read the files webpack folder, and apply the template rule to each file, passing the stylesExtension argument to be used in the template. Then, those files will be moved to our project root folder (A workspace can have more than one project and the project root is not necessarily the workspace root).

We will do the same for the tailwind config file.

// files/tailwind/tailwind.config.js
module.exports = {
  theme: {
    extend: {}
  },
  variants: {},
  plugins: []
};

// ...
function addTailwindConfigFile(projectSrcRoot: string): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    const source: Source = url('files/tailwind');
    return mergeWith(apply(source, [move(normalize(`${projectSrcRoot}/..`))]))(
      tree,
      _context,
    );
  };
}
// ...

We are using the default configuration for TailwindCSS. We could later use some parameters to adjust it.
That's it for file creation. Let's start with file updates.

// ...
function updatePackageJson(pkgJson: PackageJson): Rule {
  return (tree: Tree, _context: SchematicContext): Tree => {
    let customBuilderVersion: string = '';

    pkgJson.devDependencies = pkgJson.devDependencies || {};

    const builderVersion =
      pkgJson.devDependencies['@angular-devkit/build-angular'];


    if(builderVersion){
      const partialVersion = builderVersion
      .substring(
        builderVersion.indexOf('.') + 1,
        builderVersion.lastIndexOf('.'),
      );
      customBuilderVersion = `~${partialVersion[0]}${partialVersion[2]}.0`
    }

    pkgJson.devDependencies['@angular-builders/custom-webpack'] =
      pkgJson.devDependencies['@angular-builders/custom-webpack'] || customBuilderVersion || '~8.0.0';

    pkgJson.devDependencies['@angular-devkit/build-angular'] =
      builderVersion || '~0.800.0';

    pkgJson.devDependencies['@fullhuman/postcss-purgecss'] =
      pkgJson.devDependencies['@fullhuman/postcss-purgecss'] || '~1.2.0';

    pkgJson.devDependencies['tailwindcss'] =
      pkgJson.devDependencies['tailwindcss'] || '~1.1.2';

    tree.overwrite('package.json', JSON.stringify(pkgJson, null, 2));

    return tree;
  };
}
// ...

We are adding required dependencies if they are not already added. @angular-builders/custom-webpack version depends on @angular-devkit/build-angular. Then, we are replacing package.json with our modified version. The packages will be installed (or not) when we run the last task on ng-add.

// ...
function updateStylesFile(projectSrcRoot: string, stylesExt: string): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    const file = tree.read(`${projectSrcRoot}/styles.${stylesExt}`);

    if (!file) {
      throw new SchematicsException('Style file not found.');
    }

    const fileContent = file.toString();

    const imports = [
      '@tailwind base;',
      '@tailwind components;',
      '@tailwind utilities;',
    ];

    const recorder = tree.beginUpdate(`${projectSrcRoot}/styles.${stylesExt}`);
    imports.forEach(imported => {
      if (!fileContent.includes(imported)) {
        recorder.insertLeft(0, `${imported}\n`);
      }
    });
    tree.commitUpdate(recorder);
    return tree;
  };
}

To update our styles file, we are checking if the corresponding tailwind import exists, and adding it to the top of the file.

We are relying that styles.<stylesExt> exists. This is the default when creating a project, and we can make sure that we are adding tailwind imports at the very top of the file.

The last file updated is angular.json. We are going to replace the project builder with the custom one, and provide the custom webpack configs depending on the environment.

We won't be covering custom builders in this tutorial. We are using them to extend our build and serve commands, using the added webpack configurations, depending on the environment. This is required to be able to preprocess tailwind imports (and purge unused CSS on production).

// ...
function updateAngularConfig(
  workspace: Workspace,
  projectName: string,
  projectSrcRoot: string,
): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    workspace.projects[projectName].architect.build.builder =
      '@angular-builders/custom-webpack:browser';

    workspace.projects[
      projectName
    ].architect.build.options.customWebpackConfig = {
      path: path.join(projectSrcRoot, '..', 'webpack.config.js'),
    };

    workspace.projects[
      projectName
    ].architect.build.configurations.production.customWebpackConfig = {
      path: path.join(projectSrcRoot, '..', 'webpack-prod.config.js'),
    };

    workspace.projects[projectName].architect.serve.builder =
      '@angular-builders/custom-webpack:dev-server';
    tree.overwrite('angular.json', JSON.stringify(workspace, null, 2));
  };
}
// ...

Our final ng-add-setup schematic.

import {
  Rule,
  SchematicContext,
  Tree,
  chain,
  url,
  mergeWith,
  Source,
  template,
  apply,
  SchematicsException,
  move,
} from '@angular-devkit/schematics';

import * as path from 'path';

import { NgAddSetupOptions } from './schema';
import { normalize } from '@angular-devkit/core';
import { PackageJson, Workspace } from '../common/models';
import {
  getWorkspace,
  getProject,
  getProjectSrcRoot,
  getProjectStylesExt,
  getPackageJson,
} from '../common/utils';

export function ngAddSetup(options: NgAddSetupOptions): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    const workspace = getWorkspace(tree);
    const project = getProject(workspace, options.project);
    const root = getProjectSrcRoot(project);
    const stylesExt = getProjectStylesExt(project);
    const packageJson = getPackageJson(tree);

    return chain([
      addWebpackConfigFiles(stylesExt, root),
      addTailwindConfigFile(root),
      updateStylesFile(root, stylesExt),
      updateAngularConfig(workspace, options.project, root),
      updatePackageJson(packageJson),
    ])(tree, _context);
  };
}

function addWebpackConfigFiles(
  stylesExt: string,
  projectSrcRoot: string,
): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    const source: Source = url('files/webpack');
    return mergeWith(
      apply(source, [
        template({ stylesExt }),
        move(normalize(`${projectSrcRoot}/..`)),
      ]),
    )(tree, _context);
  };
}

function addTailwindConfigFile(projectSrcRoot: string): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    const source: Source = url('files/tailwind');
    return mergeWith(apply(source, [move(normalize(`${projectSrcRoot}/..`))]))(
      tree,
      _context,
    );
  };
}

function updatePackageJson(pkgJson: PackageJson): Rule {
  return (tree: Tree, _context: SchematicContext): Tree => {
    let customBuilderVersion: string = '';

    pkgJson.devDependencies = pkgJson.devDependencies || {};

    const builderVersion =
      pkgJson.devDependencies['@angular-devkit/build-angular'];

    if (builderVersion) {
      const partialVersion = builderVersion.substring(
        builderVersion.indexOf('.') + 1,
        builderVersion.lastIndexOf('.'),
      );
      customBuilderVersion = `~${partialVersion[0]}.${partialVersion[2]}.0`;
    }

    pkgJson.devDependencies['@angular-builders/custom-webpack'] =
      pkgJson.devDependencies['@angular-builders/custom-webpack'] ||
      customBuilderVersion ||
      '~8.0.0';

    pkgJson.devDependencies['@angular-devkit/build-angular'] =
      builderVersion || '~0.800.0';

    pkgJson.devDependencies['@fullhuman/postcss-purgecss'] =
      pkgJson.devDependencies['@fullhuman/postcss-purgecss'] || '~1.2.0';

    pkgJson.devDependencies['tailwindcss'] =
      pkgJson.devDependencies['tailwindcss'] || '~1.1.2';

    tree.overwrite('package.json', JSON.stringify(pkgJson, null, 2));

    return tree;
  };
}

function updateStylesFile(projectSrcRoot: string, stylesExt: string): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    const file = tree.read(`${projectSrcRoot}/styles.${stylesExt}`);

    if (!file) {
      throw new SchematicsException('Style file not found.');
    }

    const fileContent = file.toString();

    const imports = [
      '@tailwind base;',
      '@tailwind components;',
      '@tailwind utilities;',
    ];

    const recorder = tree.beginUpdate(`${projectSrcRoot}/styles.${stylesExt}`);
    imports.forEach(imported => {
      if (!fileContent.includes(imported)) {
        recorder.insertLeft(0, `${imported}\n`);
      }
    });
    tree.commitUpdate(recorder);
    return tree;
  };
}

function updateAngularConfig(
  workspace: Workspace,
  projectName: string,
  projectSrcRoot: string,
): Rule {
  return (tree: Tree, _context: SchematicContext) => {
    workspace.projects[projectName].architect.build.builder =
      '@angular-builders/custom-webpack:browser';

    workspace.projects[
      projectName
    ].architect.build.options.customWebpackConfig = {
      path: path.join(projectSrcRoot, '..', 'webpack.config.js'),
    };

    workspace.projects[
      projectName
    ].architect.build.configurations.production.customWebpackConfig = {
      path: path.join(projectSrcRoot, '..', 'webpack-prod.config.js'),
    };

    workspace.projects[projectName].architect.serve.builder =
      '@angular-builders/custom-webpack:dev-server';
    tree.overwrite('angular.json', JSON.stringify(workspace, null, 2));
  };
}

Unit tests

We need unit tests to check that our schematics are working properly.
Remember from our previous tutorial, that we need to create the environment first to run the schematic.
Let's start by adding the @schematics/angular package to our devDependencies. We will use it to create a workspace and a default project.

npm i --save-dev @schematics/angular

// ng-add/index.spec.ts
import {
  SchematicTestRunner,
  UnitTestTree,
} from '@angular-devkit/schematics/testing';
import * as path from 'path';
import { Tree } from '@angular-devkit/schematics';

const collectionPath = path.join(__dirname, '../collection.json');
const runner = new SchematicTestRunner('schematics', collectionPath);

describe('ng-add', () => {
  const workspaceOptions = {
    name: 'workspace',
    newProjectRoot: 'projects',
    version: '8.0.0',
  };

  const appOptions = {
    name: 'testApp',
    inlineStyle: false,
    inlineTemplate: false,
    routing: false,
    style: 'css',
    skipTests: false,
    skipPackageJson: false,
  };

  let sourceTree: UnitTestTree;

  describe('when in an angular workspace', () => {
    beforeEach(async () => {
      sourceTree = await runner
        .runExternalSchematicAsync(
          '@schematics/angular',
          'workspace',
          workspaceOptions,
        )
        .toPromise();
      sourceTree = await runner
        .runExternalSchematicAsync(
          '@schematics/angular',
          'application',
          appOptions,
          sourceTree,
        )
        .toPromise();
    });

    it('schedules two tasks by default', () => {
      runner.runSchematic('ng-add', { project: 'testApp' }, sourceTree);
      expect(runner.tasks.length).toBe(2);
      expect(runner.tasks.some(task => task.name === 'run-schematic')).toBe(
        true,
      );
      expect(runner.tasks.some(task => task.name === 'node-package')).toBe(
        true,
      );
    });

    it('will not install dependencies if skipInstall is true', () => {
      runner.runSchematic(
        'ng-add',
        { project: 'testApp', skipInstall: true },
        sourceTree,
      );
      expect(runner.tasks.length).toBe(1);
      expect(runner.tasks.some(task => task.name === 'run-schematic')).toBe(
        true,
      );
    });
  });

  describe('when not in an angular workspace', () => {
    it('should throw', () => {
      let errorMessage;
      try {
        runner.runSchematic('ng-add', {}, Tree.empty());
      } catch (e) {
        errorMessage = e.message;
      }
      expect(errorMessage).toMatch(/Could not find Angular workspace configuration/);
    });
  });
});

We are testing the number of tasks, and which tasks are running. We will also test that the schematic will throw if angular.json is not found.

We should also test that the files are created, and updated, by ng-add-setup.

// ng-add-setup/index.spec.ts
const collectionPath = path.join(__dirname, '../collection.json');

describe('ng-add-setup', () => {
  const workspaceOptions = {
    name: 'workspace',
    newProjectRoot: 'projects',
    version: '8.0.0',
  };

  const appOptions = {
    name: 'testApp',
    inlineStyle: false,
    inlineTemplate: false,
    routing: false,
    style: 'css',
    skipTests: false,
    skipPackageJson: false,
  };

  const runner = new SchematicTestRunner('schematics', collectionPath);

  let sourceTree: UnitTestTree;

  describe('CSS', () => {
    beforeEach(async () => {
      sourceTree = await runner
        .runExternalSchematicAsync(
          '@schematics/angular',
          'workspace',
          workspaceOptions,
        )
        .toPromise();
      sourceTree = await runner
        .runExternalSchematicAsync(
          '@schematics/angular',
          'application',
          appOptions,
          sourceTree,
        )
        .toPromise();
    });

    it('adds and updates files', () => {
      const tree = runner.runSchematic(
        'ng-add-setup',
        { project: 'testApp' },
        sourceTree,
      );

      expect(tree.files).toContain('/projects/testApp/tailwind.config.js');
      expect(tree.files).toContain('/projects/testApp/webpack-prod.config.js');
      expect(tree.files).toContain('/projects/testApp/webpack.config.js');
      expect(tree.files).toContain('/projects/testApp/src/styles.css');

      const stylesFile = tree.readContent('/projects/testApp/src/styles.css');

      expect(stylesFile).toContain('@tailwind base;');
      expect(stylesFile).toContain('@tailwind components;');
      expect(stylesFile).toContain('@tailwind utilities;');

      const workspace = JSON.parse(tree.readContent('angular.json'));
      const app = workspace.projects.testApp;

      expect(app.architect.build.builder).toBe(
        '@angular-builders/custom-webpack:browser',
      );

      expect(app.architect.build.options.customWebpackConfig.path).toBe(
        '/projects/testApp/webpack.config.js',
      );

      expect(
        app.architect.build.configurations.production.customWebpackConfig.path,
      ).toBe('/projects/testApp/webpack-prod.config.js');

      expect(app.architect.serve.builder).toBe(
        '@angular-builders/custom-webpack:dev-server',
      );
    });
  });

// test SCSS, SASS, etc
});

We are creating a new project, and running our schematic. Then we test that the files have been created, and updated, as expected.

Testing locally

To test the schematic locally, we can create a new angular project. (ng new <project_name>). Once we are in our project, we should run ng add <path_to_collection>. This command will install the collection, and start executing the ng-add schematic.
`

Final words

You can find the code in this repository
You can try it today!. (Pre-release, use at your own risk)
ng add @flakolefuk/tailwind-schematics.
Feel free to contribute