Forem: Fausto Braz

Authentication with Aws Cognito, Passport and NestJs (Part III)

Fausto Braz — Fri, 14 Oct 2022 15:57:31 +0000

Protecting the endpoint

For authentication, we will be using the JWT strategy. We will require the use of a bearer token generated by Cognito for accessing the protected endpoint resources.

Let's first import the PassportModule and give the JWT strategy as default.

auth.module.ts



...
import { PassportModule } from '@nestjs/passport';

@Module({
 imports: [PassportModule.register({ defaultStrategy: 'jwt' })],
    ...
})
export class AuthModule {}

Now we create a file called jwt.strategy.ts in the same directory as the auth.controller.ts.

This class will extend from PassportStrategy and pass the chosen strategy. Also, it will verify if the request is valid through the validate() callback. We also use a new environment var AWS_COGNITO_AUTHORITY that should be https://cognito-idp.YOUR_POOL_REGION.amazonaws.com/AWS_COGNITO_USER_POOL_ID, my pool region is North Virginia, so isus-east-1.
Don't forget to list it in the auth.module.ts providers since it is an @Injectable

jwt.strategy.ts




import { Injectable } from '@nestjs/common';
import { PassportStrategy } from '@nestjs/passport';
import { passportJwtSecret } from 'jwks-rsa';
import { ExtractJwt, Strategy } from 'passport-jwt';

@Injectable()
export class JwtStrategy extends PassportStrategy(Strategy) {
  constructor() {
    super({
      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
      ignoreExpiration: false,
      audience: process.env.AWS_COGNITO_COGNITO_CLIENT_ID,
      issuer: process.env.AWS_COGNITO_AUTHORITY,
      algorithms: ['RS256'],
      secretOrKeyProvider: passportJwtSecret({
        cache: true,
        rateLimit: true,
        jwksRequestsPerMinute: 5,
        jwksUri: process.env.AWS_COGNITO_AUTHORITY + '/.well-known/jwks.json',
      }),
    });
  }

  async validate(payload: any) {
    return { idUser: payload.sub, email: payload.email };
  }
}

Finally, we protect the pokemon's list endpoint using a nest guard. Let's head to our pokemon.controller.ts and add the @UseGuards() decorator passing AuthGuard('jwt') as a parameter.
Something like this:

pokemon.controller.ts



import { Controller, Get, UseGuards } from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
...

@Controller('api/v1/pokemons')
export class PokemonController {
  constructor(private readonly pokemonService: PokemonService) {}

  @UseGuards(AuthGuard('jwt'))
  @Get()
  listAllPokemons(): Array<Pokemon> {
    return this.pokemonService.listAllPokemons();
  }
}

Now, If we don't pass the bearer token produced when we log in, we will get a 401 Unauthorized from the endpoint:

And our endpoint is now protected from unwanted access.

Changing the password

To change the password, we will need to do another method called changeUserPassword in our aws-cognito.service.ts. This method will receive another DTO to get our current and new passwords. In that method, Cognito will need to authenticate the user first for changing the password later using the changePassword method:

auth-change-password-user.dto.ts



import { IsEmail, Matches } from 'class-validator';

export class AuthChangePasswordUserDto {
  @IsEmail()
  email: string;

  /* Minimum eight characters, at least one uppercase letter, one lowercase letter, one number, and one special character */

  @Matches(
    /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[$&+,:;=?@#|'<>.^*()%!-])[A-Za-z\d@$&+,:;=?@#|'<>.^*()%!-]{8,}$/,
    { message: 'invalid password' },
  )
  currentPassword: string;

  @Matches(
    /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[$&+,:;=?@#|'<>.^*()%!-])[A-Za-z\d@$&+,:;=?@#|'<>.^*()%!-]{8,}$/,
    { message: 'invalid password' },
  )
  newPassword: string;
}

aws-cognito.service.ts



...

import { AuthChangePasswordUserDto } from './dtos/auth-change-password-user.dto';

...

async changeUserPassword(
    authChangePasswordUserDto: AuthChangePasswordUserDto,
  ) {
    const { email, currentPassword, newPassword } = authChangePasswordUserDto;

    const userData = {
      Username: email,
      Pool: this.userPool,
    };

    const authenticationDetails = new AuthenticationDetails({
      Username: email,
      Password: currentPassword,
    });

    const userCognito = new CognitoUser(userData);

    return new Promise((resolve, reject) => {
      userCognito.authenticateUser(authenticationDetails, {
        onSuccess: () => {
          userCognito.changePassword(
            currentPassword,
            newPassword,
            (err, result) => {
              if (err) {
                reject(err);
                return;
              }
              resolve(result);
            },
          );
        },
        onFailure: (err) => {
          reject(err);
        },
      });
    });
  }

  ...

After we only need to do a new route in the auth.controller passing the AuthChangePasswordUserDto and calling the changeUserPassword from the aws.cognito.service.ts:

auth.controller.ts



...

@Post('/change-password')
  @UsePipes(ValidationPipe)
  async changePassword(
    @Body() authChangePasswordUserDto: AuthChangePasswordUserDto,
  ) {
    await this.awsCognitoService.changeUserPassword(authChangePasswordUserDto);
  }

 ...

After the tests, all seems to be working correctly:

Reset forgotten password

For resetting forgotten passwords, we will need two new endpoints, one for asking for a unique code and the other for switching the password.
We start by defining two new DTO's:

auth-forgot-password-user.dto.ts



...

import { IsEmail } from 'class-validator';

export class AuthForgotPasswordUserDto {
  @IsEmail()
  email: string;
}

 ...

auth-confirm-password-user.dto.ts



...

import { IsEmail, IsString, Matches } from 'class-validator';

export class AuthConfirmPasswordUserDto {
  @IsEmail()
  email: string;

  @IsString()
  confirmationCode: string;

  @Matches(
    /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[$&+,:;=?@#|'<>.^*()%!-])[A-Za-z\d@$&+,:;=?@#|'<>.^*()%!-]{8,}$/,
    { message: 'invalid password' },
  )
  newPassword: string;
}

Also, we will need to make two new methods in the aws.service.ts, to ask Cognito for a new reset code and to change the password:

aws-cognito.service.ts



...

import { AuthConfirmPasswordUserDto } from './dtos/auth-confirm-password-user.dto';
import { AuthForgotPasswordUserDto } from './dtos/auth-forgot-password-user.dto';

...

  async forgotUserPassword(
    authForgotPasswordUserDto: AuthForgotPasswordUserDto,
  ) {
    const { email } = authForgotPasswordUserDto;

    const userData = {
      Username: email,
      Pool: this.userPool,
    };

    const userCognito = new CognitoUser(userData);

    return new Promise((resolve, reject) => {
      userCognito.forgotPassword({
        onSuccess: (result) => {
          resolve(result);
        },
        onFailure: (err) => {
          reject(err);
        },
      });
    });
  }

  async confirmUserPassword(
    authConfirmPasswordUserDto: AuthConfirmPasswordUserDto,
  ) {
    const { email, confirmationCode, newPassword } = authConfirmPasswordUserDto;

    const userData = {
      Username: email,
      Pool: this.userPool,
    };

    const userCognito = new CognitoUser(userData);

    return new Promise((resolve, reject) => {
      userCognito.confirmPassword(confirmationCode, newPassword, {
        onSuccess: () => {
          resolve({ status: 'success' });
        },
        onFailure: (err) => {
          reject(err);
        },
      });
    });
  }

  ...

Pretty much the same situation on the controller where we add two new routes for the API, calling the respective service methods:

auth.controller.ts



...

  @Post('/forgot-password')
  @UsePipes(ValidationPipe)
  async forgotPassword(
    @Body() authForgotPasswordUserDto: AuthForgotPasswordUserDto,
  ) {
    return await this.awsCognitoService.forgotUserPassword(
      authForgotPasswordUserDto,
    );
  }

  @Post('/confirm-password')
  @UsePipes(ValidationPipe)
  async confirmPassword(
    @Body() authConfirmPasswordUserDto: AuthConfirmPasswordUserDto,
  ) {
    return await this.awsCognitoService.confirmUserPassword(
      authConfirmPasswordUserDto,
    );
  }
 ...

Now let's test the new endpoints:

Boom!! Everything seems to be working flawlessly.
That's all, folks.
I hope that this series helps you to understand better the Cognito and javascript integration. And you can find the repo here.

Follow me on Dev, Medium, Linkedin or Twitter to read more about my tech journey.

Authentication with Aws Cognito, Passport and NestJs (Part II)

Fausto Braz — Thu, 13 Oct 2022 11:34:21 +0000

Setting up our Nest Js project

Let's start by booting a new instance of a nest js project with nest new pokemon-app.

We also need to install some extra libraries:

To be able to communicate with the Cognito service, Amazon Cognito Identity SDK
For validating request body parameters with conditions, class-validator
Enabling serialize/deserialize objects based on some criteria, class-transformer
To get the signing keys for the JWT tokens jwks-rsa
Passport to act as auth middleware to authenticate requests
Passport strategy for JWT passport-jwt
Passport utilities for nestjs @nestjs/passport
Passport jwt types @types/passport-jwt

package.json:



...

 "dependencies": {
    "@nestjs/common": "^9.0.0",
    "@nestjs/config": "^2.2.0",
    "@nestjs/core": "^9.0.0",
    "@nestjs/platform-express": "^9.0.0",
    "amazon-cognito-identity-js": "^5.2.10",
    "@nestjs/passport": "^9.0.0",
    "@types/passport-jwt": "^3.0.7",
    "class-transformer": "^0.5.1",
    "class-validator": "^0.13.2",
    "jwks-rsa": "^2.1.5",
    "passport": "^0.6.0",
    "passport-jwt": "^4.0.0",
    "reflect-metadata": "^0.1.13",
    "rimraf": "^3.0.2",
    "rxjs": "^7.2.0"
  }

Also, to manage environment files in nestjs we need to install the nest config module via npm i @nestjs/config.
For this guide, I will keep it simple and reference them as global, and instead of dependency injection, I will use the process.env directly. You can find more documentation here.

Don't forget to create the .development.env file in your root folder.

app-module.ts:



...
@Module({
  imports: [
    ConfigModule.forRoot({
      envFilePath: '.development.env',
      isGlobal: true,
    }),
    PokemonModule,
    AuthModule,
  ],
  controllers: [],
  providers: [],
})
export class AppModule {}

Registration and authentication

After, let's navigate to the root directory and boot a module with nest g module pokemon, and create a controller and one service with nest g controller pokemon and nest g service pokemon

Now let's create a pokemon interface under the pokemon directory and export it:

pokemon.interface.ts:




export interface Pokemon {
  readonly name: string;
  readonly type: string;
}

After let's create the method in the service to list the pokemons. (It will be static to have an example of an endpoint to fetch)

pokemon.service.ts:




@Injectable()
export class PokemonService {
  listAllPokemons(): Array<Pokemon> {
    return [
      { name: 'Pikachu', type: 'Electric' },
      { name: 'Volpix', type: 'Fire' },
      { name: 'Flabébé', type: 'Fairy' },
    ];
  }
}

Let's reference the endpoint path in the pokemon controller and inject the PokemonService to be consumed:

pokemon.controller.ts:



...

import { PokemonService } from './pokemon.service';

@Controller('api/v1/pokemons')
export class PokemonController {
  constructor(private readonly pokemonService: PokemonService) {}

  @Get()
  listAllPokemons(): Array<Pokemon> {
    return this.pokemonService.listAllPokemons();
  }
}

We can run npm run start:dev. If everything builds fine, we should list the pokemon's at http://localhost:3000/api/v1/pokemons

Now we will build our auth module only to allow authenticated users to fetch the info from that endpoint. Let's generate another module with nest g module auth and another controller with nest g controller auth.

Next, let's create our DTOs, under the auth folder, for the user registration and login:

auth-login-user:



...

import { IsEmail, Matches } from 'class-validator';

export class AuthLoginUserDto {
  @IsEmail()
  email: string;

  /* Minimum eight characters, at least one uppercase letter, one lowercase letter, one number, and one special character */

  @Matches(
    /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[$&+,:;=?@#|'<>.^*()%!-])[A-Za-z\d@$&+,:;=?@#|'<>.^*()%!-]{8,}$/,
    { message: 'invalid password' },
  )
  password: string;
}

auth-register-user:



...

import { IsEmail, IsString, Matches } from 'class-validator';

export class AuthRegisterUserDto {
  @IsString()
  name: string;

  @IsEmail()
  email: string;

  /* Minimum eight characters, at least one uppercase letter, one lowercase letter, one number, and one special character */

  @Matches(
    /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[$&+,:;=?@#|'<>.^*()%!-])[A-Za-z\d@$&+,:;=?@#|'<>.^*()%!-]{8,}$/,
    { message: 'invalid password' },
  )
  password: string;

}

After let's write the Cognito service with the register and authentication methods, generate a new service inside the auth module, and don't forget to reference it in that provider's module:

aws-cognito.service.ts:




import { Injectable } from '@nestjs/common';
import {
  AuthenticationDetails,
  CognitoUser,
  CognitoUserAttribute,
  CognitoUserPool,
} from 'amazon-cognito-identity-js';
import { AuthLoginUserDto } from './dtos/auth-login-user.dto';
import { AuthRegisterUserDto } from './dtos/auth-register-user.dto';

@Injectable()
export class AwsCognitoService {
  private userPool: CognitoUserPool;

  constructor() {
    this.userPool = new CognitoUserPool({
      UserPoolId: process.env.AWS_COGNITO_USER_POOL_ID,
      ClientId: process.env.AWS_COGNITO_CLIENT_ID,
    });
  }

  async registerUser(authRegisterUserDto: AuthRegisterUserDto) {
    const { name, email, password } = authRegisterUserDto;

    return new Promise((resolve, reject) => {
      this.userPool.signUp(
        email,
        password,
        [
          new CognitoUserAttribute({
            Name: 'name',
            Value: name,
          }),
        ],
        null,
        (err, result) => {
          if (!result) {
            reject(err);
          } else {
            resolve(result.user);
          }
        },
      );
    });
  }

  async authenticateUser(authLoginUserDto: AuthLoginUserDto) {
    const { email, password } = authLoginUserDto;
    const userData = {
      Username: email,
      Pool: this.userPool,
    };

    const authenticationDetails = new AuthenticationDetails({
      Username: email,
      Password: password,
    });

    const userCognito = new CognitoUser(userData);

    return new Promise((resolve, reject) => {
      userCognito.authenticateUser(authenticationDetails, {
        onSuccess: (result) => {
         resolve({
            accessToken: result.getAccessToken().getJwtToken(),
            refreshToken: result.getRefreshToken().getToken(),
          });
        },
        onFailure: (err) => {
          reject(err);
        },
      });
    });
  }
}

Now we should save in the development.env the values for AWS_COGNITO_USER_POOL_ID and AWS_COGNITO_CLIENT_ID that we held in the first part of the guide.

In our auth.controller.ts, we can now inject the AWS Cognito service and register and authenticate the user:

auth.controller.ts




import {
  Body,
  Controller,
  Post,
  UsePipes,
  ValidationPipe,
} from '@nestjs/common';
import { AwsCognitoService } from './aws-cognito.service';
import { AuthLoginUserDto } from './dtos/auth-login-user.dto';
import { AuthRegisterUserDto } from './dtos/auth-register-user.dto';

@Controller('api/v1/auth')
export class AuthController {
  constructor(private awsCognitoService: AwsCognitoService) {}

  @Post('/register')
  async register(@Body() authRegisterUserDto: AuthRegisterUserDto) {
    return this.awsCognitoService.registerUser(authRegisterUserDto);
  }

  @Post('/login')
  @UsePipes(ValidationPipe)
  async login(@Body() authLoginUserDto: AuthLoginUserDto) {
    return this.awsCognitoService.authenticateUser(authLoginUserDto);
  }
}

Start your application with npm run start:dev and if everything starts up without errors, we can give our registry endpoint a go to see if it's working:

Seem's to be working, the user is created and verified. Let's test the login:

That's all for the second part; in the third part, we will protect the endpoint and the resources using Passport and Jwt Authentication.
Stay tuned 😊

Authentication with Aws Cognito, Passport and NestJs (Part I)

Fausto Braz — Wed, 12 Oct 2022 15:21:40 +0000

Authentication is one of the most complex parts of developing applications. It's also one of the most important because it's how you know who you're dealing with. When building a platform, authentication is even more crucial—you need to ensure that only people who are supposed to be accessing your service can do so.

There are many different ways to go about it, but today we'll discuss how to use AWS Cognito, Passport, and NestJs to create an authentication system for your app. This is a beginner tutorial, and it should take you a long to better understand authentication with cloud providers.

But first, let's look at this diagram to see how everything will be connected:

Aws Cognito

Aws Cognito is an Amazon service that can provide authentication, authorization, and user management out of the box, and you can learn more about it here

The first step is setting up your AWS account; if you don't have one, you can sign up for one here. Also, you can see the related costs with each service on that page.

After we have our account, we will search for the Cognito service like so:

Let's click Create user pool, on step1 let's keep the Cognito user pool checked and choose only the email to sign in:

On the configure security requirements, let's disabled MFA because it will add unnecessary complexity to this guide.

When configuring the sign-up experience, let's add the name to the required attributes.

In the next step for configuring the message delivery, let's send emails with Cognito.

On the app integration, we named our poll pokemon-app, and we created a new app client name called node-app, going with the default values for now.

In our last step, let's verify everything is correct and create the user poll.

Next, select the user pool in the table, go for the app integration tab, and create a Cognito domain. (I've used https://pokemon-app.auth.us-east-1.amazoncognito.com)

We should save the Cognito Domain and the Client ID value for later usage in the guide.

Let's change the content from the verification email to a link:

Now let's grant Cognito access to our user; let's search for IAM, the service to manage access to AWS resources:

If you already have a user select the user and click Add permissions go for the Attach existing policies directly separator and search for AmazonEsCognitoAccess:

Select the policy next, and assign it to the user.

If you don't have a user, you must set up one and add the security policy. (You can set the policy on the second step when creating a new one)

In the next part, we will set up our next js project and integrate it with Cognito. Please stay tuned 😊

Cross-framework web components library 📚 using Lit (Part III)

Fausto Braz — Mon, 05 Sep 2022 14:55:38 +0000

Exporting and building the library

We will export the components we create to be reused later when we distribute the node package via the npm registry. For that, we need first to create an index.ts under the src directory:

That file will export the components via barrels exports like so:

export * from './components/card';
export * from './components/cards';

After we need to set the output of our typescript transpilation for that, we point the outDir in the tsconfig.json for the lib directory in the project root, like so:

Another essential part is to configure the package.json file at the root of the project; we should point the main property to lib/index.js and update all the other properties:

If everything is well configured, we should be able to run the tsc
command and one version of the library in javascript should be generated under the ./lib directory.

Distributing the library

We will use the npm registry to distribute the library via a node package. If you don't have an account, you will need to create one here

After you log in via the console using the npm login command, your package for being uploaded will require the package.json in place, a version, and a name. Also, if you use namespaces, don't forget that they are private by default.

The npm publish command will successfully upload your package with minimum effort and two-factor authentication if everything is in place. You can find the node package from this tutorial here

If you find some difficulty, please follow along with this more detailed tutorial, props to Jon Wood

Usage with Angular

Before every sandbox, we must install the node package using npm i inclusive-web-components.

For using it with Angular, you need to define the CUSTOM_ELEMENTS_SCHEMA in the app.module.ts file to be able to add custom elements to the app.component.html since Angular ignores custom elements named with dashes and throws an error.

After, you will need to import the lib in the app.component.ts and pass the configuration via the [cards] property, and you should have a collection of card components now:

Usage with React

Since custom components are not treated as React components, we need to use JSON.stringify to pass data to the card attribute since the attribute is treated as a string, which will happen to custom events too.

Instead of doing this, let's use the use-custom-element package to have a cleaner approach. npm i use-custom-element.

Next, we pass the configuration using the useCustomElement method and bind the result to the custom element, and we should have the same result as in the previous sandbox:

Usage with Svelte

Well, this was the most straightforward approach since Svelte is the newest framework of the pack and has better support for custom elements.
It was just declaring the lib into the package.json and import in App.svelte passed all the configuration to the custom element et voila we have a web component running 🚀:

This is all in this series, and I hope this tutorial will help you.
Feel free to reach out in any doubt arises.

Follow me on Dev, Medium, Linkedin or Twitter to read more about my tech journey.

Cross-framework web components library 📚 using Lit (Part II)

Fausto Braz — Wed, 31 Aug 2022 13:27:46 +0000

Testing

After we conclude our card component is time to test it. I have used the testing package from Open Web Components, and you can find the documentation here in conjunction with jasmine and karma.

We start describing what component will be tested and defining what we will mock as component properties:

import { Card } from './card';

describe('Card Component', () => {
    let el: Card;

    const card = {
        altText: 'Je suis a image',
        ctaText: 'Click me',
        image: 'http://example.com/image/',
        link: 'http://example.com/link/',
        text: 'amazing text',
        textDesc: 'other amazing text for test',
        textDescLink: 'http://example.com/author/',
        title: 'amazing title',
    };

}

After that, before the test runs, we boot a fixture that will pass a Card component with our custom configuration, and we check if the element is defined, checking the instanceOf:

...

import { assert, expect, fixture, html } from '@open-wc/testing';

describe('Card Component', () => {
    ...

    beforeEach(async () => {
        el = await fixture<Card>(html` <card-image .card=${card}></card-image> `);
    });

    it('is defined', () => {
        assert.instanceOf(el, Card);
    });

}

If everything is well configured, we run the test, and we should have one successful test:

Let's have a bit more coverage on that component:

...

describe('Card Component', () => {
      ...

      it('renders the image', () => {
        const image = el.shadowRoot?.querySelector('img');
        expect(image).to.exist;
        expect(image?.alt).to.equal(card.altText);
        expect(image?.src).to.equal(card.image);
      });

      it('renders the title', () => {
        const title = el.shadowRoot?.querySelector('#card-link');
        expect(title).to.exist;
        expect(title?.getAttribute('href')).to.equal(card.link);
        expect(title?.textContent).to.equal(card.title);
      });

      it('renders the text', () => {
        const text = el.shadowRoot?.querySelector('p');
        expect(text).to.exist;
        expect(text?.textContent).to.equal(card.text);
      });

      it('renders the cta text', () => {
        const ctaText = el.shadowRoot?.querySelector('.cta a');
        expect(ctaText).to.exist;
        expect(ctaText?.textContent).to.equal(card.ctaText);
      });

      it('renders the description link', () => {
        const textDesc = el.shadowRoot?.querySelector('small a');
        expect(textDesc).to.exist;
        expect(textDesc?.getAttribute('href')).to.equal(card.textDescLink);
        expect(textDesc?.textContent).to.equal(card.textDesc);
      });

      it('dispatch the mousedown event', () => {
        el.mouseDown();
        expect(el.down).to.be.a('number');
      });

}

This should leverage the coverage to more than 80%.

Cards component

We will be doing a second component where we can pass the configuration to have multiple cards.
This exposes the ability to reuse one internal component and do another with other purposes that can have a different configuration. Also, we will be using lit directives.

We start by doing a new component at the same level as card.ts:

...

import { LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('cards-images')
export class Cards extends LitElement {}

After we define the external @property, that basically will receive an array of CardConfig objects:

...

import { customElement, property } from 'lit/decorators.js';

@customElement('cards-images')
export class Cards extends LitElement {

    @property({ type: Array }) cards!: CardConfig[];

}

We can now render the cards container and use the repeat directive to generate various instances of the card based on the configuration we passed in the @property:

...

import { html, LitElement } from 'lit';
import { repeat } from 'lit/directives/repeat.js';

@customElement('cards-images')
export class Cards extends LitElement {

    ...

    render() {
    return html` <div class="cards">
      <ul>
        ${repeat(this.cards, (current) => html` <card-image .card=${current}></card-image> `)}
      </ul>
    </div>`;
  }

}

To finalize, we only need to add the component styles and the shared ones:

...

import { css, html, LitElement } from 'lit';
import { sharedStyles } from './shared/style';

const componentStyle = css`
  .cards > ul {
    list-style: none;
    margin: 0;
    padding: 0;
  }

  @supports (display: grid) {
    .cards > ul {
      display: grid;
      grid-template-columns: repeat(auto-fill, minmax(15rem, 1fr));
      grid-column-gap: 1.5rem;
      grid-row-gap: 1.5rem;
    }
  }
`;


@customElement('cards-images')
export class Cards extends LitElement {

  static styles = [sharedStyles, componentStyle];

    ...

}

And now, you should have a component that will render like this:

In the next part, we will cover distributing the lib via a node package using the npm registry and how to use the components in different frameworks/libs environments.

Cross-framework web components library 📚 using Lit (Part I)

Fausto Braz — Tue, 30 Aug 2022 09:30:00 +0000

Web Components are a new suite of technologies that allow us to create custom elements and encapsulate their functionality away from the rest of the code, making them highly reusable and shareable in your web apps, perfect for developing highly custom design systems.

For this example, we will create two card components, porting from one of my favorite pattern libraries, Inclusive Components props to Heydon Pickering for the excellent book.

Using Lit

Creating, scaling, and maintaining web components with vanilla Javascript can rapidly become messy, so I've chosen to enhance the expressiveness by using lit that makes use of Typescript.
Anyhow it would be best if you did not forget to take a look at the vanilla JS implementations to understand how the Web Components implementation work under the hood.

You can find the lit documentation under this link and the original Html and Js code of the card element here.

So, let's get our hands dirty

I've started initiating an empty git repo at link.
Feel free to add your contribution, and improvements are always welcome.

I've added Typescript, Eslint, Jasmine, and Open Web Components libraries, to keep all along with the best code practices and to test the components after:

My folder structure will be a components folder that can have shared stuff.
In this case, we will share some styles between the two components.

Next, we start creating a new class decorator @customElement ('card-image') in card.ts that extends from LitElement that inherits and encapsulates some methods to access the web components API:

import { LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('card-image')
export class Card extends LitElement {}

After we can start to define an interface to pass the component properties, I've declared it in the same file, but feel free to create a separated one, if you think that will be reused:

...

export interface CardConfig {
  altText: string;
  ctaText: string;
  image: string;
  link: string;
  text: string;
  textDesc: string;
  textDescLink: string;
  title: string;
}

@customElement('card-image')
export class Card extends LitElement {}

It is time to define the configuration object and the Html that will be returned in the render method:

...

@customElement('card-image')
export class Card extends LitElement {

    @property({ type: Object }) card!: CardConfig;

    render() {
        return html`
          <li class="card">
            <div class="img">
                <img src="${this.card.image}" alt="${this.card.altText}" />
            </div>
            <div class="text">
              <h2>
                <a id="card-link" href="${this.card.link}" aria-describedby="desc-a-card"
                  >${this.card.title}</a
                >
              </h2>
              <p>${this.card.text}</p>
              <span class="cta" aria-hidden="true" id="desc-a-card">${this.card.ctaText}</span>
              <small><a href="${this.card.textDescLink}">${this.card.textDesc}</a></small>
            </div>
          </li>
        `;
  }


}

Now we can define the styles; we also import a shared style, which is the font definition:

...

import { sharedStyles } from './shared/style';

const componentStyle = css`
  h2 {
    margin-bottom: 1rem;
  }

  .card + .card {
    margin-top: 1.5rem;
  }

  @supports (display: grid) {
    .card + .card {
      margin-top: 0;
    }
  }

  .card {
    cursor: pointer;
    border: 1px solid;
    border-radius: 0.25rem;
    display: flex;
    flex-direction: column;
    position: relative;
  }

  .card .text {
    padding: 1rem;
    flex: 1 0 auto;
    display: flex;
    flex-direction: column;
    cursor: pointer;
  }

  .card p {
    max-width: 60ch;
  }

  .card .img {
    height: 6.5rem;
    clip-path: polygon(0 0, 100% 0, 100% 100%, 0 calc(100% - 1rem));
  }

  .card .img img {
    width: 100%;
    height: 100%;
    object-fit: cover;
    filter: grayscale(100%);
  }

  .card a {
    outline: none;
  }

  .card h2 a {
    text-decoration: none;
  }

  .card h2 a:focus {
    text-decoration: underline;
  }

  .card h2:focus-within ~ .cta {
    box-shadow: 0 0 0 0.125rem;
  }

  .card:focus-within h2 a:focus {
    text-decoration: none;
  }

  .card small {
    display: block;
    text-align: right;
  }

  .card small a {
    position: relative;
    text-decoration: none;
    padding: 0.5rem 0;
  }

  .card small a:hover,
  .card small a:focus {
    text-decoration: underline;
  }

  .card .text > * + * {
    margin-top: 0.75rem;
  }

  .card .text > :nth-last-child(3) {
    margin-bottom: 0.75rem;
  }

  .card .text > :nth-last-child(2) {
    margin-top: auto;
    padding-top: 0.75rem;
  }

  .cta {
    padding: 0.75rem;
    border: 1px solid;
    border-radius: 0.25rem;
    text-align: center;
  }

  .cta > a {
    text-decoration: none;
  }
`;

@customElement('card-image')
export class Card extends LitElement {

    static styles = [sharedStyles, componentStyle];

    ...

}

Finally, we will set up two events to solve the redundant click event problem listed here

...

@customElement('card-image')
export class Card extends LitElement {

    ...

    @query('#card-link') cardLinkEl!: HTMLAnchorElement;

    render() {
    return html`
      <li class="card">
        <div class="img">
          <img
            src="${this.card.image}"
            alt="${this.card.altText}"
            @mousedown="${this.mouseDown}"
            @mouseup="${this.handleClick}"
          />
        </div>
        <div class="text">
          <h2>
            <a
              id="card-link"
              href="${this.card.link}"
              @mousedown="${this.mouseDown}"
              @mouseup="${this.handleClick}"
              aria-describedby="desc-a-card"
              >${this.card.title}</a
            >
          </h2>
          <p>${this.card.text}</p>
          <span class="cta" aria-hidden="true" id="desc-a-card"
            ><a href="${this.card.link}">${this.card.ctaText}</a>
          </span>
          <small><a href="${this.card.textDescLink}">${this.card.textDesc}</a></small>
        </div>
      </li>
    `;
  }

  mouseDown() {
    this.down = Number(new Date());
  }

  handleClick() {
    this.up = Number(new Date());
    const total = this.up - this.down;

    if (total < 200) {
      this.cardLinkEl.click();
    }
  }

}

And now we should have a single card component that looks like this:

In the next part, we will test this component and do another that reuses the original card.