Forem: Marc Stammerjohann

Send Emails with NestJS

Marc Stammerjohann — Thu, 18 Mar 2021 10:56:54 +0000

This post gets you up and running with everything you need to know about sending Emails using nest-modules/mailer in your NestJS backend. 👇

📧 Sending emails using Nodemailer

🧩 Creating email templates with handlebars (alternatives: pug or ejs)

⚙️ Configure smtp via .env file

Install Dependencies

Add the @nestjs-modules/mailer and the peer dependency nodemailer to your Nest application. Choose one of the supported template engines for creating your email templates: handlebars, pug or ejs.

npm install --save @nestjs-modules/mailer nodemailer

# pick one template adapter and install
npm install --save handlebars
# or
npm install --save pug
# or
npm install --save ejs

In this guide, you are creating email templates using handlebars.

npm install --save @nestjs-modules/mailer nodemailer handlebars

Mail Module

Let's begin with creating a mail module and service via the Nest CLI and followed by creating a templates folder.

nest g module mail
nest g service mail

mkdir src/mail/templates

Import the MailerModule into your MailModule and configure your mail server transport via smtp. Provide a default from email address to consistently use the same mail throughout your application. No worries, you can always override the default whenever necessary. Last step, configure the templates folder and the adapter in this case HandlebarsAdapter. Find out more about the other template adapters in the Mailer documentation.

import { MailerModule } from '@nestjs-modules/mailer';
import { HandlebarsAdapter } from '@nestjs-modules/mailer/dist/adapters/handlebars.adapter';
import { Module } from '@nestjs/common';
import { MailService } from './mail.service';
import { join } from 'path';

@Module({
  imports: [
    MailerModule.forRoot({
      // transport: 'smtps://user@example.com:topsecret@smtp.example.com',
      // or
      transport: {
        host: 'smtp.example.com',
        secure: false,
        auth: {
          user: 'user@example.com',
          pass: 'topsecret',
        },
      },
      defaults: {
        from: '"No Reply" <noreply@example.com>',
      },
      template: {
        dir: join(__dirname, 'templates'),
        adapter: new HandlebarsAdapter(), // or new PugAdapter() or new EjsAdapter()
        options: {
          strict: true,
        },
      },
    }),
  ],
  providers: [MailService],
  exports: [MailService], // 👈 export for DI
})
export class MailModule {}

Export the MailService to provide it via Dependency Injection (DI) for your controllers, resolvers and services.

Handlebars Mail Template

Create your first email template confirmation.hbs in the src/mail/templates folder. Add the following simple template for a user confirmation.

<p>Hey {{ name }},</p>
<p>Please click below to confirm your email</p>
<p>
    <a href="{{ url }}">Confirm</a>
</p>

<p>If you did not request this email you can safely ignore it.</p>

Those curly brackets are handlebars expressions and you will provide the context later while sending an email.

When you build your Nest application you will notice that the build output is missing your template files (dist/mail/templates).

By default, Nest only distributes TypeScript compiled files (.js and .d.ts) during the build step. To distribute your .hbs files, open your nest-cli.json and add your templates directory to the assets property in the global compilerOptions.

{
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "assets": ["mail/templates/**/*"] // 👈 or "**/*.hbs" all files ending with .hbs
    "watchAssets": true // 🤖 copy assets in watch mode
  }
}

Build your Nest application again and now your template files are included in the build output.

Sending Mail

Add MailerService to your own MailService and implement your mailing logic here. Let's send a user confirmation email using the template confirmation.hbs. You need to provide {{ name }} and {{ url }} under the context key. Read the Handlebars documentation for more background like Nested input objects.

import { MailerService } from '@nestjs-modules/mailer';
import { Injectable } from '@nestjs/common';
import { User } from './../user/user.entity';

@Injectable()
export class MailService {
  constructor(private mailerService: MailerService) {}

  async sendUserConfirmation(user: User, token: string) {
    const url = `example.com/auth/confirm?token=${token}`;

    await this.mailerService.sendMail({
      to: user.email,
      // from: '"Support Team" <support@example.com>', // override default from
      subject: 'Welcome to Nice App! Confirm your Email',
      template: 'confirmation', // `.hbs` extension is appended automatically
      context: { // ✏️ filling curly brackets with content
        name: user.name,
        url,
      },
    });
  }
}

// ./../user/user.entity
export interface User {
  email: string;
  name: string;
}

Using Mail Service

Add the MailModule to the imports list of your modules which need to use the MailService.

import { Module } from '@nestjs/common';
import { AuthController } from './auth.controller';
import { AuthService } from './auth.service';
import { MailModule } from './mail/mail.module';

@Module({
  imports: [MailModule], // 📧
  controllers: [AuthController],
  providers: [AuthService],
})
export class AuthModule {}

Now you can add MailService to the constructor of your controllers, resolvers and services

import { Injectable } from '@nestjs/common';
import { MailService } from './../mail/mail.service';
import { User } from './../user/user.entity';

@Injectable()
export class AuthService {
  constructor(private mailService: MailService) {}

  async signUp(user: User) {
    const token = Math.floor(1000 + Math.random() * 9000).toString();
    // create user in db
    // ...
    // send confirmation mail
    await this.mailService.sendUserConfirmation(user, token);
  }
}

Move configurations to dotenv file

Currently, the mail server configurations are hardcoded in to the MailModule. Nest provides a configuration module which enables you to load your configurations and credentials from .env files.

Install the @nestjs/config dependency.

# config 
npm i --save @nestjs/config

Add the ConfigModule to the imports list of your AppModule.

import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { AuthModule } from './auth/auth.module';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true, // no need to import into other modules
    }),
    AuthModule,
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Create a .env file in your root directory and don't forget to add in your .gitingore file.

# mail
MAIL_HOST=smtp.example.com
MAIL_USER=user@example.com
MAIL_PASSWORD=topsecret
MAIL_FROM=noreply@example.com

# optional
MAIL_TRANSPORT=smtp://${MAIL_USER}:${MAIL_PASSWORD}@${MAIL_HOST}

Reopen MailModule and change MailerModule.forRoot to MailerModule.forRootAsync, this allows you to inject and use the ConfigService.

import { MailerModule } from '@nestjs-modules/mailer';
import { HandlebarsAdapter } from '@nestjs-modules/mailer/dist/adapters/handlebars.adapter';
import { Module } from '@nestjs/common';
import { MailService } from './mail.service';
import { join } from 'path';
import { ConfigModule, ConfigService } from '@nestjs/config';

@Module({
  imports: [
    MailerModule.forRootAsync({
      // imports: [ConfigModule], // import module if not enabled globally
      useFactory: async (config: ConfigService) => ({
        // transport: config.get("MAIL_TRANSPORT"),
        // or
        transport: {
          host: config.get('MAIL_HOST'),
          secure: false,
          auth: {
            user: config.get('MAIL_USER'),
            pass: config.get('MAIL_PASSWORD'),
          },
        },
        defaults: {
          from: `"No Reply" <${config.get('MAIL_USER')}>`,
        },
        template: {
          dir: join(__dirname, 'templates'),
          adapter: new HandlebarsAdapter(),
          options: {
            strict: true,
          },
        },
      }),
      inject: [ConfigService],
    }),
  ],
  providers: [MailService],
  exports: [MailService],
})
export class MailModule {}

Time to add your own mail server configuration, start Nest and send your first mails 📧 to your users

Tailwind CSS Purge: Optimize Angular for Production

Marc Stammerjohann — Tue, 15 Dec 2020 09:55:51 +0000

By design, Tailwind CSS generates a large amount of utility classes for your development build. For your Angular application you want the best performance by only including the classes you are actually using in your production build. Tailwind got you covered! PurgeCSS is build-in making it easy to tree-shake unused Tailwind styles for your application.

You are going to learn how to setup Tailwind's purge option to optimize Tailwind CSS in your Angular and for your Scully Jamstack application.

The purge options in this post have been tested with Angular 11 and Tailwind CSS 2.0, it also works with Angular 10 and Tailwind CSS 1.9.

Get Started

Get ready with a new or existing Angular + Tailwind CSS application

ng new app-name

# add tailwind
ng add ngx-tailwind

# optional - add jamstack with Scully
ng add @scullyio/init

Now use Tailwind CSS utility classes in your Angular application HTML template, using apply in your stylesheets or even in your TypeScript files via @HostBinding(...).

Purge unused Tailwind CSS utilities in Angular

Tailwind provides a purge option in the tailwind.config.js file. Purge removes only classes generated by Tailwind or styles added to the @layer directive. Custom CSS or third-party CSS like Angular Material or Prism.js will not be removed.

Simply provide all your template paths as an array to the purge option. For an Angular application this would be all HTML and TS files in your src directory. TS files should be included as they might reference class names using e.g. @HostBinding(...).

module.exports = {
  purge: ["./src/ **/*.html", "./src/** /*.ts"],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

Use *.{html,ts} to match multiple file types in the same directory

module.exports = {
- purge: ["./src/ **/*.html", "./src/** /*.ts"],
+ purge: ["./src/**/*.{html,ts}"],
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

Trigger Tailwind to automatically purge your CSS by setting NODE_ENV=production during your ng build step. If you used ngx-tailwind schematics to setup Tailwind it automatically added a production script to your package.json. Additionally, the latest release of ngx-tailwind@1.1.0 adds the above purge options automatically to your tailwind.config.js.

{
  "scripts": {
    "build:prod": "NODE_ENV=production ng build --prod"
  }
}

Now run npm run build:prod to only include used Tailwind CSS utilities in your Angular production build. This even works great in your Scully application

Advanced Purge options

purge also accepts an options object for further optimizations. Available purge options are enabled, content for your template paths, preserveHtmlElements, layers, mode and last options to pass it directly to PurgeCSS. The defaults for these options are:

module.exports = {
  purge: {
    // enabled: true, // enabled by `NODE_ENV=production` or enable manually
    mode: 'layers', // or 'all' ☠️ be careful
    preserveHtmlElements: true, // or false ⚠️ not generally recommended
    layers: ['base', 'components', 'utilities'], // remove layers to ignore from purging
    content: [], // add your template paths
    options: { /* PurgeCSS options */}
  },
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

Too use the object syntax for the purge option add the template paths to the content option

module.exports = {
  purge: {
    content: ["./src/**/*.{html,ts}"]
  },
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

Go ahead and provide additional options to the purge object to further optimize your production build based on your application. For specific configurations pass it directly to PurgeCSS using the options key. You can provide safelist, blocklist, extractors and more.

module.exports = {
  purge: {
    content: ["./src/ **/*.html", "./src/** /*.ts"],

    // These options are passed through directly to PurgeCSS
    options: {
      safelist: ['bg-red-500', /^mat-/],
      blocklist: ['bg-orange-500', /^cdk-/],
      extractors: [],
      ...
    }
  },
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

Let's improve purging for a Scully application by writing an extractor for your Markdown content files to detect which HTML tags and CSS classes are actually used.

Purge Scully Markdown content

Scully organizes the content of your static-site in Markdown files. Add the path to your Markdown files e.g. './blog/**/*.md' to the content array. Create an extractor targeting only files with the Markdown extension md.

module.exports = {
  purge: {
    content: ['./src/ **/*.{html,ts}', './blog/** /*.md'],
    options: {
      extractors: [
        {
          extensions: ['md'],
          extractor: (content) => {

            return [];
          },
        },
      ],
    },
  },
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

Before matching HTML elements and CSS classes you need to parse the Markdown content to HTML. Scully uses marked to parse your Markdown content files. Let's require it in the tailwind.config.js and parse the content in the extractor.

const marked = require('marked');

module.exports = {
  purge: {
    content: ['./src/ **/*.{html,ts}', './blog/** /*.md'],
    options: {
      extractors: [
        {
          extensions: ['md'],
          extractor: (content) => {
            content = marked(content);

            return [];
          },
        },
      ],
    },
  },
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

Let's use the Regex used by blog.tailwindcss.com to find all used HTML elements and classes. Also set the mode: 'all' ☠️ and preserveHtmlElements: false ⚠️ to remove unused tags like h4 and more.

const marked = require('marked');

module.exports = {
  purge: {
    model: 'all',
    preserveHtmlElements: false,
    content: ['./src/ **/*.{html,ts}', './blog/** /*.md'],
    options: {
      extractors: [
        {
          extensions: ['md'],
          extractor: (content) => {
            content = marked(content);

            // Capture as liberally as possible, including things like `h-(screen-1.5)`
            const broadMatches = content.match(/[^<>"'`\s]*[^<>"'`\s:]/g) || []

            // Capture classes within other delimiters like .block(class="w-1/2") in Pug
            const innerMatches =
              content.match(/[^<>"'`\s.(){}[\]#=%]*[^<>"'`\s.(){}[\]#=%:]/g) || []

            return broadMatches.concat(innerMatches);
          },
        },
      ],
    },
  },
  darkMode: false, // or 'media' or 'class'
  theme: {
    extend: {},
  },
  variants: {
    extend: {},
  },
  plugins: [],
};

Perfect, now your Angular or Scully applications are optimized for production and you are ready to deploy it to Firebase Hosting or other services.

Firebase Hosting: Preview and Deploy via GitHub Actions

Marc Stammerjohann — Mon, 09 Nov 2020 13:18:24 +0000

You start building an Angular or a Scully application and at some point you want to invite colleagues, friends, family or customers to check it out. Firebase Hosting allows to host your static or dynamic web apps for FREE 💸. You are setting up a GitHub workflow deploying your Scully app (works with Angular and any other web framework) to preview and live channel.

Demo source code and hosted on Firebase 🔥.

Before you dive straight into this you will need a

Firebase Account
GitHub Account and a private or public repo for your web app

Use your existing web application or create a new one by following Angular 10 with Tailwind CSS or Jamstack: Angular + Scully + Tailwind CSS to get started.

Getting started

Install Firebase CLI minimum in v8.12.0 for preview channels support.

# install firebase cli
npm install -g firebase-tools

# init firebase hosting
firebase init hosting
# hosting already setup, prepare GitHub workflow
firebase init hosting:github

Follow the CLI prompts to setup Firebase hosting and GitHub workflow.

Firebase Hosting Setup

Start by selecting an existing Firebase project, create one in Firebase console, or create a new project through the CLI.

Next enter the public directory containing all files of your web app including index.html which is uploaded to Firebase hosting

# Angular
dist/<project-name>

# Scully `outDir` specified in your scully.<project-name>.ts defaults to
dist/static

You can change the public directory anytime in firebase.json file.

Answer the next question "Configure as a single-page app (rewrite all urls to /index.html)?" with yes for Angular apps (and other single-page apps) and no for Scully apps (and other static-site apps).

Let Firebase CLI initialize your GitHub repository for automatic deploys. Several steps are taken care by the Firebase CLI for you

Creating a Firebase service account with deployment permissions to Firebase Hosting
Encrypt and add secret to GitHub repository
Creating GitHub workflow yaml files

Enter no for the next two questions to overwrite dist/static/404.html and dist/static/index.html, let those be generated by Scully.

Select a GitHub repository to setup your secret token for your workflow and enter a build script to build Angular and Scully like npm ci && npm run build:ci. For a Scully build add the following two scripts to your package.json:

"build:ci": "npm run build:prod && npm run scully:ci"
"scully:ci": "scully -- --host='0.0.0.0' --scanRoutes --serverTimeout=60000",

If you like to deploy to live channel on merged Pull Request answer with yes and enter your branch name for the live channel for example main.

GitHub Workflow

You should have now two workflows if you used the Firebase CLI. The workflows use the GitHub Action Deploy to Firebase Hosting, currently in alpha release.

Workflow to deploy to a preview channel on Pull Request .github/workflows/firebase-hosting-pull-request.yml

# This file was auto-generated by the Firebase CLI
# https://github.com/firebase/firebase-tools

name: Deploy to Firebase Hosting on PR
'on': pull_request
jobs:
  build_and_preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: 'npm ci && npm run build:ci'
      # Add additional build steps here
      # - run: ...
      - uses: FirebaseExtended/action-hosting-deploy@v0
        with:
          repoToken: '${{ secrets.GITHUB_TOKEN }}'
          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT }}'
          projectId: your-firebase-project-id
          # default expire value 7 days
          # expires: 7d
        env:
          FIREBASE_CLI_PREVIEWS: hostingchannels

Workflow to deploy to your live channel on push to main branch .github/workflows/firebase-hosting-merge.yml

# This file was auto-generated by the Firebase CLI
# https://github.com/firebase/firebase-tools

name: Deploy to Firebase Hosting on merge
'on':
  push:
    branches:
      - main
jobs:
  build_and_deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: 'npm ci && npm run build:ci'
      # Add additional build steps here
      # - run: ...
      - uses: FirebaseExtended/action-hosting-deploy@v0
        with:
          repoToken: '${{ secrets.GITHUB_TOKEN }}'
          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT }}'
          channelId: live
          projectId: your-firebase-project-id
        env:
          FIREBASE_CLI_PREVIEWS: hostingchannels

Deploying to the live channel requires channelId set to live. If left blank the action creates a new preview channel using the PR-branch name.

Additional option for the preview channel is expires which defaults to 7 days. Change the expiration of your preview channel to maximum 30 days. It supports the syntax h for hours, d for days and w for weeks, for example 19h, 30d, 3w.

Preview and Live Channel

Create a Pull Request with the above GitHub workflows and you should see the GitHub Action start building

After the workflow finished successfully, the Firebase action creates a comment with the preview URL for this PR.

View the preview of your web app, if you are not happy with your changes repeat it. Here is the Scully demo blog in the preview channel on Firebase Hosting.

Finally, merge your Pull Request to trigger the deployment to the live channel. Find the Scully demo blog on the live channel.

It was never easier to ship improvements to your web application to preview, ask colleagues or customers for a review 👌❓ and simply deploy your changes to the live channel 🚀 by merging your PR.

Jamstack: Angular + Scully + Tailwind CSS

Marc Stammerjohann — Tue, 27 Oct 2020 11:46:18 +0000

Scully is a static site generator build for the web framework Angular. You learn how to build a Jamstack project with Angular and Scully. Let's add Tailwind CSS for easy styling, the cherry 🍒 on the cake 🍰.

TL;DR

Create a new Angular project, add Scully and Tailwind CSS using schematics. Angular provides schematics for generating and performing installation steps automatically for you - used by Scully and ngx-tailwind. 💯

ng new app-name --style=scss --routing true
cd app-name

# add scully
ng add @scullyio/init

# add scully blog
ng generate @scullyio/init:blog

# add tailwind
ng add ngx-tailwind

Or follow along with the source code. For more information about Angular and Tailwind read the in-depth guide Angular 10 with Tailwind CSS.

Remove unused CSS for production build 🧹

Tailwind generates a lot of CSS styles which are very helpful during development. Before deploying the Scully app remove all unused CSS using the purge option in tailwind.config.js. Provide paths of your template and TypeScript files:

module.exports = {
  future: {
    // removeDeprecatedGapUtilities: true,
    // purgeLayersByDefault: true,
  },
+ purge: ["./src/ **/*.html", "./src/** /*.ts"],
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
};

Tailwind automatically purges unused styles when NODE_ENV is set to production. Use the script added by ngx-tailwind

npm run build:prod

Open app.component.html and add a header template using Tailwind utility styles.

<div class="max-w-3xl mx-auto px-4 sm:px-6 xl:max-w-5xl xl:px-0">
  <header class="flex justify-between items-center py-10">
    <div>
      <a href="/" class="text-xl font-semibold"> Angular + Scully + Tailwind = 🚀 </a>
    </div>
    <div>
      <a href="https://github.com/notiz-dev/angular-scully-tailwindcss" class="font-medium text-gray-500 hover:text-gray-700"> Source Code &rarr; </a>
    </div>
  </header>

  <main>
    <!-- Displaying Angular routes -->
    <router-outlet></router-outlet>
  </main>
</div>

Customize your own header on play.tailwindcss.com.

Start Scully

Getting started to serve Angular as a Jamstack app for the first time. Follow the steps in this order.

First build Angular app

npm run build:prod

Build Scully app

npm run scully

All pre-rendered static site files are generated in ./dist/static. For each page you will see an index.html file.

Scully app

npm run scully:serve

Open your favorite browser and go to http://localhost:1668/ for the Scully static server and http://localhost:1864/ for the Angular server.

You should see on both links - Angular top 👆, Scully bottom 👇.

What's added by Scully? 🔍

Scully creates a config file scully.<projectname>.config.ts at the root folder. You will look at this in a moment.

Additionally, after your first Scully build new few new files are generated by Scully. Let's add those to the .gitignore file

# Scully
.scully
scully.log
src/assets/scully-routes.json
scully/plugins/*.js
scully/plugins/*.js.map

scully-routes.json contains all information about your available routes including the front matter data which you will access later in your blog post page.

Markdown blog

One 💍 command to rule your blog

ng generate @scullyio/init:blog

Do you need more flexibility? Try running the following and answer a few questions:

ng generate @scullyio/init:markdown

Now your blog is setup. A new route like /blog/<slug> has been added, re-build your Angular app and discover the new route with Scully

npm run scully -- --scanRoutes

Serve your Scully app and navigate to the first generated post in your browser localhost:1668/blog/<slug>.

Scully creates for each blog post an index.html inside your dist/static/blog directory.

Style blog post page

Alright, you got your first blog post page rendered, but let's be honest 🧐 it needs a few adjustment. The current blog post page is missing the blog post title , publishing date and has unstyled content.

Scully has a build in service ScullyRoutesService to access the front matter of your blog posts. It exposes all published posts under ScullyRoutesService.available$ and the current page with ScullyRoutesService.getCurrent().

Open your generated blog.component.ts and use ScullyRoutesService.getCurrent()

import { Component, OnInit, ViewEncapsulation } from '@angular/core';
import { ActivatedRoute, Router } from '@angular/router';
import { ScullyRoute, ScullyRoutesService } from '@scullyio/ng-lib';
import { Observable } from 'rxjs';

@Component({
  selector: 'app-blog',
  templateUrl: './blog.component.html',
  styleUrls: ['./blog.component.scss'],
  preserveWhitespaces: true,
  encapsulation: ViewEncapsulation.Emulated,
})
export class BlogComponent implements OnInit {
  currentPost$: Observable<ScullyRoute> = this.scully.getCurrent();

  constructor(
    private router: Router,
    private route: ActivatedRoute,
    private scully: ScullyRoutesService
  ) {}

  ngOnInit() {}
}

In your template use async pipe to unwrap the Observable to access the title and publishedAt (custom property).

<article>
  <header *ngIf="currentPost$ | async as currentPost" class="pt-6 xl:pb-10">
    <div class="space-y-1 text-center">
      <dl class="space-y-10" *ngIf="currentPost.publishedAt">
        <div>
          <dt class="sr-only">Published on</dt>
          <dd class="text-base leading-6 font-medium text-gray-500">
            <time [dateTime]="currentPost.publishedAt"> {{ currentPost.publishedAt | date: "dd MMMM yyyy" }} </time>
          </dd>
        </div>
      </dl>
      <div>
        <h1 class="text-3xl leading-9 font-extrabold text-gray-900 tracking-tight sm:text-4xl sm:leading-10 md:text-5xl md:leading-14">{{ currentPost.title }}</h1>
      </div>
    </div>
  </header>

  <!-- This is where Scully will inject the static HTML -->
  <scully-content></scully-content>
</article>

Check out Tailwind Blog which is used here as reference for styling a simple and clean blog.

Update your blog front matter to set published to true, add publishedAt with a datetime string and remove any unpublished slug, also add some placeholder content:


--------
title: 2020-10-23-blog
description: 10 Top tips about your next Pizza Hawaii
published: true
publishedAt: 2020-10-31T13:37:00.000Z
--------

# Pizza 🍕

Eat **pizza** hawaii *everyday*. ~~Don't forget~~ the 🧀 on your `pizza`.



```
var pizza = "Eat 🍕";
alert(pizza);
```



## Hawaii

Ordered List

1. 🍍
2. 🥓
3. 🧀

Unordered List

* 🧀
* 🍍
* 🥓

### Diavolo

> Pizza might be very 🌶️

Last but not least, remove all styles from blog.component.scss. Now re-build Angular, Scully and serve Scully to see the new blog post header

Awesome 🤩 looks much better. What about the unstyled content? 🤨 Go and install Tailwind Typography plugin applying styles to your markdown content.

npm install -D @tailwindcss/typography

Add the plugin to your tailwind.config.js

module.exports = {
  future: {
    // removeDeprecatedGapUtilities: true,
    // purgeLayersByDefault: true,
  },
  purge: ["./src/ **/*.html", "./src/** /*.ts"],
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [require('@tailwindcss/typography')],
};

Now wrap <scully-content></scully-content> with the prose class provided by the Tailwind Typography plugin:

<article>
  <header>
    ...
  </header>

  <div class="prose max-w-none pt-10 pb-8">
    <!-- This is where Scully will inject the static HTML -->
    <scully-content></scully-content>
  </div>
</article>

Blog post content is now styled 😎. How easy was that? Feel free to further customize the styles to your brand or personal style.

One more thing is left, listing all available posts and navigating to the post slug.

Blog Overview Page

Generate a new component for your route /blog displaying all available posts using ScullyRoutesService.available$.

ng g module blogs --route blogs --module blog/blog.module

Change the path of your new route in blog-routing.module.ts from blogs to empty to match the /blog route.

const routes: Routes = [
  {
+ path: '',
- path: 'blogs',
    loadChildren: () =>
      import('../blogs/blogs.module').then((m) => m.BlogsModule),
  },
  {
    path: ':slug',
    component: BlogComponent,
  },
  {
    path: '**',
    component: BlogComponent,
  },
];

If you like to automatically redirect to /blog open app-routing.module.ts

const routes: Routes = [
+ { path: '', redirectTo: 'blog', pathMatch: 'full' },
  {
    path: 'blog',
    loadChildren: () => import('./blog/blog.module').then((m) => m.BlogModule),
  },
];

Now create a reference for all available blog posts in blogs.component.ts filtering out pages with routes starting only with /blog/. Additionally, sort your posts in descending order by the publishedAt date.

import { Observable } from 'rxjs';
import { filter, map } from 'rxjs/operators';
import { Component, OnInit } from '@angular/core';
import { ScullyRoute, ScullyRoutesService } from '@scullyio/ng-lib';

@Component({
  selector: 'app-blogs',
  templateUrl: './blogs.component.html',
  styleUrls: ['./blogs.component.scss'],
})
export class BlogsComponent implements OnInit {
  available$: Observable<ScullyRoute[]>;

  constructor(private scully: ScullyRoutesService) {}

  ngOnInit(): void {
    this.available$ = this.scully.available$.pipe(
      map((r) => r.filter((page) => page.route.startsWith('/blog/'))),
      map((r) => r.sort((page1, page2) => new Date(page2.publishedAt).getTime() - new Date(page1.publishedAt).getTime()))
    );
  }
}

Important to note you have to import ScullyLibModule in your blogs.module.ts to access ScullyRoutesService.

Add your blog name and loop over all posts in your template

<div class="pt-6 pb-8 space-y-2 md:space-y-5">
  <h1 class="text-3xl font-extrabold bg-clip-text text-transparent bg-gradient-to-r from-orange-500 via-yellow-400 to-yellow-200 tracking-tight sm:text-4xl md:text-6xl">Company Blog</h1>
  <p class="text-lg leading-7 text-gray-500">All the latest Company news.</p>
</div>

<ul class="divide-y divide-gray-200">
  <li *ngFor="let post of available$ | async" class="py-12">
    <article class="space-y-2 xl:grid xl:grid-cols-4 xl:space-y-0 xl:items-baseline">
      <dl>
        <dt class="sr-only">Published on</dt>
        <dd class="text-base leading-6 font-medium text-gray-500">
          <time [dateTime]="post.publishedAt"> {{ post.publishedAt | date: "dd MMMM yyyy" }} </time>
        </dd>
      </dl>
      <div class="space-y-5 xl:col-span-3">
        <div class="space-y-6">
          <h2 class="text-2xl leading-8 font-bold tracking-tight">
            <a [routerLink]="post.route" class="text-gray-900 hover:text-gray-700"> {{ post.title }} </a>
          </h2>
          <div class="prose max-w-none text-gray-500">{{ post.description }}</div>
        </div>
        <div class="text-base leading-6 font-medium">
          <a [routerLink]="post.route" class="text-orange-500 hover:text-orange-600"> Read more &rarr; </a>
        </div>
      </div>
    </article>
  </li>
</ul>

Now all you need is an idea and time to write it down. Creating your next blog post is as easy as 💆

ng generate @scullyio/init:post --name="Cool post"

Made possible by Scully schematics.

What are you wait for? 😄 Now it's time for you to create your own blog 🚀. Need more inspiration? notiz.dev is build using Scully and Tailwind CSS. 😉

DBML generator for Prisma

Marc Stammerjohann — Wed, 16 Sep 2020 08:29:27 +0000

Introducing 🥳 Prisma DBML Generator automatically generating a DBML schema based on your Prisma Schema.

Simply install the DBML generator

npm install -D prisma-dbml-generator

Add the generator to your schema.prisma

generator dbml {
  provider = "prisma-dbml-generator"
}

Running npx prisma generate for the following Prisma schema

model User {
  id Int @id @default(autoincrement())
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
  email String @unique
  name String?
  posts Post[]
  profile Profile?
  /// user role
  role Role @default(USER)
}

/// User profile
model Profile {
  id Int @default(autoincrement()) @id
  bio String?
  user User @relation(fields: [userId], references: [id])
  userId Int @unique
}

model Post {
  id Int @id @default(autoincrement())
  title String
  content String?
  published Boolean @default(false)
  author User? @relation(fields: [authorId], references: [id])
  authorId Int?
}

/// user role
enum Role {
  ADMIN /// allowed to do everything
  USER
}

generates the following schema.dbml to prisma/dbml

Table User {
  id Int [pk, increment]
  createdAt DateTime [default: `now()`, not null]
  updatedAt DateTime [not null]
  email String [unique, not null]
  name String
  posts Post
  profile Profile
  role Role [not null, default: 'USER', note: 'user role']
}

Table Profile {
  id Int [pk, increment]
  bio String
  user User [not null]
  userId Int [unique, not null]

  Note: 'User profile'
}

Table Post {
  id Int [pk, increment]
  title String [not null]
  content String
  published Boolean [not null, default: false]
  author User
  authorId Int
}

Enum Role {
  ADMIN
  USER
}

Ref: Profile.userId - User.id

Ref: Post.authorId > User.id

Copy the schema.dbml content and visualize it as an Entity-Relationship Diagram:

You should see this output each time you run npx prisma generate

$ npx prisma generate
Environment variables loaded from prisma/.env

✔ Generated Prisma Client to ./node_modules/@prisma/client in 281ms

✔ Generated DBML Schema to ./prisma/dbml in 5ms

You can now start using Prisma Client in your code:

``
import { PrismaClient } from '@prisma/client'
// or const { PrismaClient } = require('@prisma/client')

const prisma = new PrismaClient()
``

Explore the full API: http://pris.ly/d/client

Check out the readme and give it a try with your own Prisma Schema 😎.

Introducing NestJS Prisma Schematics

Marc Stammerjohann — Fri, 07 Aug 2020 10:59:37 +0000

Until now, adding Prisma to a NestJS application requires a few manual steps - installing @prisma/cli and @prisma/client, creating a PrismaService and (eventually) adding a Dockerfile.

I am excited to release nestjs-prisma - a set of schematics to perform all steps necessary to add Prisma to your NestJS application automatically.

All you need to do is run the following command in your Nest app:

nest add nestjs-prisma

Do you need more options? I got you covered, you can go a step further and specify a Prisma version if you like:

nest add nestjs-prisma --prismaVersion 2.4.1

Or go crazy by adding a Dockerfile for your Nest app and a docker-compose.yaml with a PostgreSQL database.

nest add nestjs-prisma --addDocker

Check out all options and give it a try with your Nest app.

Dockerizing a NestJS app with Prisma and PostgreSQL

Marc Stammerjohann — Fri, 31 Jul 2020 11:43:39 +0000

Docker 🐳 enables you to build consistent containers of your applications for your development, testing and production environments. In this post you will dockerize a NestJS 😸 application with Prisma connecting to a PostgreSQL 🐘 database.

Requirements for this post are

Docker installed
NestJS application with Prisma

You can find the full source code on GitHub.

Use this prisma schema to follow along:

datasource db {
  provider = "postgresql"
  url = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model Food {
  id Int @id @default(autoincrement())
  name String
}

And a .env file in your prisma directory for a dummy PostgreSQL connection url:

DATABASE_URL=postgresql://johndoe:randompassword@localhost:5432/mydb?schema=public

TL;DR Multi-stage Dockerfile

Create a Dockerfile in the root of your Nest application

touch Dockerfile

Open the Dockerfile and use the multi-stage build steps 🤙

FROM node:12 AS builder

# Create app directory
WORKDIR /app

# A wildcard is used to ensure both package.json AND package-lock.json are copied
COPY package*.json ./
COPY prisma ./prisma/

# Install app dependencies
RUN npm install
# Generate prisma client, leave out if generating in `postinstall` script
RUN npx prisma generate

COPY . .

RUN npm run build

FROM node:12

COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package*.json ./
COPY --from=builder /app/dist ./dist

EXPOSE 3000
CMD ["npm", "run", "start:prod"]

But wait… what is going in the Dockerfile 🤔❓ See the breakdown for each step below.

Don't forget to create a .dockerignore file next to your Dockerfile:

node_modules
npm-debug.log

The COPY command ignores those local files and folder and won't copy them into your Docker image to prevent overwriting your installed modules in your image.

Your application structure should look like this:

Breakdown of the multi-stage Dockerfile

Let's breakdown the Dockerfile step-by-step

🏗 Builder Image

FROM node:12 AS builder

The first line tells Docker to use the latest LTS version 12 for node as the base image to build the container from. To optimize the container image size you are using the multistage-build and assign a name to your base image AS builder.

Note : Before updating to a newer version of node check the support of Nest, Prisma and other dependencies

🧰 Working directory

# Create app directory
WORKDIR /app

Create the working directory for your application which stores your code. All commands (RUN, COPY) are executed inside this directory.

📦 Installation

# A wildcard is used to ensure both package.json AND package-lock.json are copied
COPY package*.json ./
COPY prisma ./prisma/

# Install app dependencies
RUN npm install
# Generate prisma client, leave out if generating in `postinstall` script
RUN npx prisma generate

Next you need to install your app dependencies inside the Docker image. package.json and package-lock.json are copied over. Generating the Prisma Client requires the schema.prisma file. COPY prisma ./prisma/ copies the whole prisma directory in case you also need the migrations.

Note : Only package*.json and prisma directory is copied in this step to take advantage of the cached Docker layers.

Install all dependencies RUN npm install (dev too). This allows you to build the Nest application inside the Docker image. Now its also the time to generate the Prisma Client. Leave this step out if you are generating the client in the a postinstall script.

⚙️ Build app

COPY . .

RUN npm run build

To build your Nest application copy all of your source files (exceptions in .dockerignore) into the Docker image. Now it's time to build your app RUN npm run build.

👟 Run your app

FROM node:12

The second FROM is the second stage in the multi-stage build and is used to run your application.

COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package*.json ./
COPY --from=builder /app/dist ./dist

Copy from your builder image only files and folders required to run the Nest app.

EXPOSE 3000
CMD ["npm", "run", "start:prod"]

Nest apps usually bind to port 3000, EXPOSE the same port for your Docker image. Last step is the command to run the Nest application using CMD.

Build and run your image

Enter the following command in the directory of your Dockerfile. Give your build image a name using the -t flag to easily start, stop and remove it.

# give your docker image a name
docker build -t <your username>/nest-api .

# for example
docker build -t nest-api .

After your Docker image is successfully build start it with this command

docker run -p 3000:3000 --env-file prisma/.env -d <your username>/nest-api

Prisma Client requires the DATABASE_URL environment variable which you pass using the --env-file prisma/.env flag. Use this .env file for additional environment variables (Port, JWT Secret etc.) or copy it into your root folder.

Open up localhost:3000 to verify that your Nest app is running with Docker.

Add docker-compose with PostgreSQL

Docker Compose allows you to define and run multiple Docker container together.Here you are setting up a Docker compose file for the Nest application and a PostgreSQL database.

Create the Docker compose file

touch docker-compose.yml

Add following services to docker.compose.yml

version: '3.7'
services:
  nest-api:
    container_name: nest-api
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - 3000:3000
    depends_on:
      - postgres
    env_file:
      - .env

  postgres:
    image: postgres:12
    container_name: postgres
    restart: always
    ports:
      - 5432:5432
    env_file:
      - .env
    volumes:
      - postgres:/var/lib/postgresql/data

volumes:
  postgres:
    name: nest-db

The first service nest-api is building the Docker image based on your Dockerfile for your Nest app with Prisma. The second service is creating a postgres database using the postgres Docker image in version 12. For the Postgres image set POSTGRESQL_USER, POSTGRESQL_PASSWORD and POSTGRES_DB environment variables in a .env file next to your docker-compose.yml

POSTGRESQL_USER=prisma
POSTGRESQL_PASSWORD=topsecret
POSTGRES_DB=food

To connect to the PostgreSQL database Docker image configure the DATABASE_URL in your .env file. Fill in your values into the Postgres connection url format

postgresql://USER:PASSWORD@HOST:PORT/DB?schema=NAME&sslmode=prefer

In this example add the following variable to the .env file. The HOST is when connecting from another Docker image either the service name or the container name - both postgres.

DATABASE_URL=postgresql://prisma:topsecret@postgres:5432/food?schema=food&sslmode=prefer

Time 🕙 to start your Nest app and Postgres Docker image. Make sure the ports 3000 and 5432 are not in use already.

docker-compose up
# or detached
docker-compose up -d

You should have the following two docker containers started

Open again localhost:3000 to verify that your Nest app is running with Docker. Also verify that your endpoints using the Prisma Client have access to the Postgres DB.

Prisma Migrate Postgres Docker Container

Replace the host postgres with localhost if you want to perform Prisma migrations locally of your Postgres Docker container. Update the DATABASE_URL in prisma/.env to

DATABASE_URL=postgresql://prisma:topsecret@localhost:5432/food?schema=food&sslmode=prefer

Now you can run npx prisma migrate save --experimental and npx prisma migrate save --experimental or even seed the database if you like.

Perfect, now sit back and relax 🏝 and let Docker do the work for you.

Angular 10 with Tailwind CSS

Marc Stammerjohann — Mon, 13 Jul 2020 09:26:45 +0000

Learn how to use utility-first CSS framework Tailwind CSS with Angular using ngx-build-plus.

This guide works for both Tailwind CSS v1 and v2 and Angular v10 and v11.

Angular Project

You need the Angular CLI to create a new Angular project.

ng new app-name --style=scss
cd app-name

Follow the instruction to manually configure Angular w/ Tailwind 🍬🍫🍪 or jump directly to the shortcut.

Setup

Start by adding dependencies for Tailwind, Postcss and ngx-build-plus for angular.

npm i -D tailwindcss autoprefixer postcss postcss-import postcss-loader postcss-scss

ng add ngx-build-plus

Create a webpack.config.js in your root folder to configure Postcss with Tailwind.

touch webpack.config.js

module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        loader: 'postcss-loader',
        options: {
          postcssOptions: {
            ident: 'postcss',
            syntax: 'postcss-scss',
            plugins: [
              require('postcss-import'),
              require('tailwindcss'),
              require('autoprefixer'),
            ],
          },
        },
      },
    ],
  },

Now open angular.json file to apply the extra webpack config to generate Tailwind styles during ng build, ng serve and ng test. If you used the schematics ng add ngx-build-plus it automatically replaces @angular-devkit/build-angular with ngx-build-plus in your angular.json. Additionally, add the extraWebpackConfig to each build step. In the end your angular.json should look like this:

"architect": {
  "build": {
-   "builder": "@angular-devkit/build-angular:browser",
+   "builder": "ngx-build-plus:browser",
    "options": {
+     "extraWebpackConfig": "webpack.config.js",
      ...
    }
    ...
  },
  "serve": {
-   "builder": "@angular-devkit/build-angular:dev-server",
+   "builder": "ngx-build-plus:dev-server",
    "options": {
+     "extraWebpackConfig": "webpack.config.js",
      ...
    }
    ...
  },
  "test": {
-   "builder": "@angular-devkit/build-angular:karma",
+   "builder": "ngx-build-plus:karma",
    "options": {
+     "extraWebpackConfig": "webpack.config.js",
      ...
    }
    ...
  },

Perfect, now it's time to generate the Tailwind config npx tailwindcss init or for full config npx tailwindcss init --full.

Almost there. Add Tailwind base styles to your src/styles.scss file

@import 'tailwindcss/base';

@import 'tailwindcss/components';

@import 'tailwindcss/utilities';

Now go ahead serve your app, you are ready to style your Angular app with Tailwind utility classes.

… wait a moment, we need to purge the unused CSS styles from Tailwind.

Remove unused CSS Styles

We can use the new purge option in tailwind.config.js.

module.exports = {
  purge: ['./src/ **/*.html', './src/** /*.ts'],
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
};

Unused styles are removed by Tailwind when you run your build with NODE_ENV set to production. Add "build:prod": "NODE_ENV=production ng build --prod", to your scripts in package.json. Now run npm run build:prod to get a production build with only used Tailwind styles.

CSS instead of SCSS

Using CSS instead of SCSS? No problem. You don't need to install postcss-scss.

npm i -D tailwindcss autoprefixer postcss postcss-import postcss-loader 

ng add ngx-build-plus

Update also your webpack.config.js:

module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        loader: 'postcss-loader',
        options: {
          postcssOptions: {
            ident: 'postcss',
            syntax: 'postcss',
            plugins: [
              require('postcss-import'),
              require('tailwindcss'),
              require('autoprefixer'),
            ],
          },
        },
      },
    ],
  },
};

Finally add Tailwind base styles to src/styles.css.

@import 'tailwindcss/base';

@import 'tailwindcss/components';

@import 'tailwindcss/utilities';

Shortcut aka Angular Schematics

If you also think the steps above are tedious … Don't look any further.

Angular Schematics 💪 to the rescue. Gary created a schematic to add Tailwind to an Angular project. Simply run the schematic to automatically configure Tailwind:

ng add ngx-tailwind

Use Tailwind CSS utility classes

Now go crazy with Tailwind's CSS utility classes in your Angular app.

Add them to your HTML template class, [class.hover:...]="true" or use them with ngClass

<span class="inline-block bg-red-500 rounded-full px-3 py-1 text-sm font-semibold text-white" [class.hover:bg-red-700]="hoverMe">
  #angular
</span>

Add it to your stylesheet

span {
  @apply inline-block bg-red-500 rounded-full px-3 py-1 text-sm font-semibold text-white;
} 

span:hover {
  @apply bg-red-700;
}

Note : @apply is not compiled when using it in an Angular library due to missing support for postcss of ng-packagr

Or use @HostBinding in your *.ts files

@HostBinding('class')
get classes() {
  return 'bg-red-500 px-4';
}

@HostBinding('class.hidden')
get classes() {
  return this.isHidden;
}

Add the following snippet to your src/app.component.html to see if Tailwind styles the following card. (Don't worry about the picture its random)

<div class="max-w-sm mx-auto mt-10 rounded overflow-hidden shadow-lg space-y-4">
  <img
    class="h-64 w-full object-cover object-center"
    src="https://source.unsplash.com/random"
    alt="Random unsplash photo"
  />
  <div class="px-6">
    <div class="font-bold text-xl">Angular w/ Tailwind</div>
    <p class="text-gray-700 text-base">
      Lorem ipsum dolor sit amet, consectetur adipisicing elit. Voluptatibus
      quia, nulla! Maiores et perferendis eaque, exercitationem praesentium
      nihil.
    </p>
  </div>
  <div class="px-6 pb-4 space-x-2">
    <a
      href="https://angular.io"
      target="_blank"
      rel="noreferrer"
      class="inline-block bg-red-500 rounded-full px-3 py-1 text-sm font-semibold text-white hover:bg-red-700"
    >
      #angular
    </a>
    <a
      href="https://tailwindcss.com"
      target="_blank"
      rel="noreferrer"
      class="inline-block bg-indigo-500 rounded-full px-3 py-1 text-sm font-semibold text-white hover:bg-indigo-700"
    >
      #tailwind
    </a>
    <a
      href="https://notiz.dev"
      target="_blank"
      rel="noreferrer"
      class="inline-block bg-blue-200 rounded-full px-3 py-1 text-sm font-semibold text-gray-700 hover:bg-blue-400"
    >
      #notiz
    </a>
  </div>
</div>

In the next post you will create an Angular component for a floating form field based on my last post Floating Form Field with Tailwind CSS.

Migrations

Upgrading from Tailwind CSS v1 to v2

To upgrade you project from Tailwind CSS v1.x to v2.0 run the following install command

npm i -D tailwindcss@latest postcss@latest autoprefixer@latest postcss-import@latest

Read the full Upgrade Guide to update your custom tailwind.config.js (e.g. your color palette) and replace removed classes from your template (e.g. shadow-outline and shadow-xs).

Update postcss-loader from 3.x to 4.x

postcss-loader has new breaking changes when updating from version 3.x to 4.x. Huge thanks to @phileagleson 👏 who pointed out that options for Postcss have moved to the postcssOptions. Therefore, update your webpack.config.js as follows when updating to postcss-loader@4.x

module.exports = {
  module: {
    rules: [
      {
        test: /\.scss$/,
        loader: 'postcss-loader',
        options: {
-          ident: 'postcss',
-          syntax: 'postcss-scss',
-          plugins: () => [
-            require('postcss-import'),
-            require('tailwindcss'),
-            require('autoprefixer'),
-          ],
+          postcssOptions: {
+           ident: 'postcss',
+            syntax: 'postcss-scss',
+            plugins: [
+              require('postcss-import'),
+              require('tailwindcss'),
+              require('autoprefixer'),
            ],
          },
        },
      },
    ],
  },
};

All webpack.config.js examples are updated to use the new postcssOptions for postcss-loader@4.x.

Floating Form Field with Tailwind CSS

Marc Stammerjohann — Thu, 28 May 2020 20:54:11 +0000

In the following lesson you will learn how to use Tailwind CSS utility-first approach to create a floating form field known from Material Design. This is inspired by the awesome video from fireship.io.

You can follow along in a new project or get the source code from GitHub.

Setup

Let's start in an empty directory and setup up a default package.json file using npm init -y.

Setup Tailwind CSS

Setup Tailwind by installing

npm i -D tailwindcss postcss-cli autoprefixer

Generate a Tailwind config file as you will customize Tailwind for the floating form field later.

npx tailwindcss init

Create postcss.config.js file requiring tailwindcss and autoprefixer as a plugin:

module.exports = {
  plugins: [
    require("tailwindcss"),
    require("autoprefixer")
  ]
};

Create your tailwind styles under css/tailwind.css

@tailwind base;
@tailwind components;
@tailwind utilities;

Add those scripts to your package.json one to build and the other to watch changes made to the tailwind.css file.

"scripts": {
  "build": "postcss css/tailwind.css -o public/build/tailwind.css",
  "dev": "postcss css/tailwind.css -o public/build/tailwind.css -w"
},

Setup HTML

Start with the following simple HTML layout - create an index.html in the public directory.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>FFFwT</title>

    <link rel="stylesheet" href="build/tailwind.css" />
  </head>
  <body class="antialiased p-10">
    <form>
      <div>
        <input type="text" name="username" placeholder=" " />
        <label for="username">Username</label>
      </div>
    </form>
  </body>
</html>

You can use live-server to start a dev-server with live reload.

live-server public

Here you have your starting point - an input and a label.

Let's add styles to create a floating form field.

Floating Form Field

Focus Border

Start by adding a bottom border to the div using border-b-{width}

<div class="border-b-2">
  <input type="text" name="username" placeholder=" " />
  <label for="username">Username</label>
</div>

To change the border color when the input is focused use the pseudo-class focus-within. Enable the focus-within variant in Tailwind for borderColor by adding it in the tailwind.config.js under the variants section:

variants: {
  borderColor: ['responsive', 'hover', 'focus', 'focus-within'],
},

Now add focus-within:border-blue-500 to change the border color on focus

<div class="my-4 border-b-2 focus-within:border-blue-500">
  <input type="text" name="username" placeholder=" " />
  <label for="username">Username</label>
</div>

Floating Label

Begin with changing the position of the div to relative so that you can use top to control the position of the label. Add class="absolute top-0" to the label.

input is an inline element, add the Tailwind block class to change it to a block element. Also set the input width to 100% with w-full to tap the input on the whole form field. Additionally, add appearance-none and focus:outline-none to the input to remove browser specific styles.

<div class="relative my-4 border-b-2 focus-within:border-blue-500">
  <input type="text" name="username" placeholder=" " class="block w-full appearance-none focus:outline-none" />
  <label for="username" class="absolute top-0">Username</label>
</div>

Currently the label is covering the input field and preventing you from focusing the input 🙈.

Let's change the z-index of the label to be behind the input field by setting it to z-index: -1. Extend the Tailwind theme to generate a negative z-index for you:

theme: {
  extend: {
    zIndex: {
      "-1": "-1",
    },
  },
}

Add -z-1 class to the label, now the label is not visible anymore. Add bg-transparent to the input.

<div class="relative my-4 border-b-2 focus-within:border-blue-500">
  <input type="text" name="username" placeholder=" " class="block w-full appearance-none focus:outline-none bg-transparent" />
  <label for="username" class="absolute top-0 -z-1">Username</label>
</div>

The label is visible again and the input field can be focused by taping on the label too 🐵.

Next make the label float above the input, again, using the pseudo-class focus-within. Open your tailwind.css and add the following CSS selector:

input:focus-within ~ label {

}

Now use Tailwind's @apply to transform, scale and change the label text color on input focus.

input:focus-within ~ label {
 @apply transform scale-75 -translate-y-6 text-blue-500;
}

Also add duration-300 to your label class to control the labels transition duration.

Awesome the label is floating 🎈, however, it stops floating when you remove the focus from the input 😞. The label should float if the input field has some content. Target the placeholder, if its not shown input:not(:placeholder-shown) ~ label thus the input has content and the label should float.

input:focus-within ~ label,
input:not(:placeholder-shown) ~ label {
  @apply transform scale-75 -translate-y-6;
}

input:focus-within ~ label {
  @apply text-blue-500;
}

Yeah 🤩, the label floats on focus and if the input has content. It seems the label is not aligned with the input field. Set transform-origin on the label to 0%. Let Tailwind generate it for you, open tailwind.config.js and add it to the theme section:

theme: {
  extend: {
    transformOrigin: {
      "0": "0%",
    },
    zIndex: {
      "-1": "-1",
    },
  },
}

Now add origin-0 to the label and finally you have your own floating form field made with Tailwind CSS 😍🚀

Building a form

Let's build a form field by duplicating the floating form field or by extracting the styles with @apply.

Add space-y-{size} to the form to add margin between your input fields. You could also wrap it with a card.

 <form class="max-w-sm mx-auto rounded-lg shadow-xl overflow-hidden p-6 space-y-10">
  <h2 class="text-2xl font-bold text-center">Login</h2>
  <div class="relative border-b-2 focus-within:border-blue-500">
    <input type="text" name="username" placeholder=" " class="block w-full appearance-none focus:outline-none bg-transparent" />
    <label for="username" class="absolute top-0 -z-1 duration-300 origin-0">Username</label>
  </div>
  <div class="relative border-b-2 focus-within:border-blue-500">
    <input type="text" name="email" placeholder=" " class="block w-full appearance-none focus:outline-none bg-transparent" />
    <label for="email" class="absolute top-0 -z-1 duration-300 origin-0">Email</label>
  </div>
  <div class="relative border-b-2 focus-within:border-blue-500">
    <input type="password" name="password" placeholder=" " class="block w-full appearance-none focus:outline-none bg-transparent" />
    <label for="password" class="absolute top-0 -z-1 duration-300 origin-0">Password</label>
  </div>
</form>

Here you have your first form using the floating form field

Next, try out another style - Outline Form Field.

Outline Form Field

In this style the form field has an outline all around and the label floats into the outline. Reuse the floating form field and change border-b-2 to border-2 this gives you the outline.

Add padding p-4 to create space inside the outline and increase the font size text-lg of the input and the label.

<div class="relative border-2 focus-within:border-blue-500">
  <input type="text" name="username" placeholder=" " class="block p-4 w-full text-lg appearance-none focus:outline-none bg-transparent" />
  <label for="username" class="absolute top-0 p-4 text-lg -z-1 duration-300 origin-0">Username</label>
</div>

Look at our outline form field

Focus the input and you notice the label is not covering up the outline.

To make the label cover up the outline customize the floating CSS applied to the outline form field. Duplicate the custom CSS in your tailwind.css and add .outline class to both selectors. Add outline class to the div around your input and label.

.outline input:focus-within ~ label,
.outline input:not(:placeholder-shown) ~ label {
  @apply transform scale-75 -translate-y-6;
}

Update a few styles on the label to remove the top and bottom padding - py-0. Also reduce the left and right padding to px-1, add margin left ml-3 to align it with the input. Reset the z-index to z-0 that the label is above the outline. Finally, reduce the translate y value until the label is perfectly matching the outline.

.outline input:focus-within ~ label,
.outline input:not(:placeholder-shown) ~ label {
  @apply transform scale-75 -translate-y-4 z-0 ml-3 px-1 py-0;
}

Perfect the label is exactly on the outline, but the line is still visible.

To hide the outline set the background of the label to the same background of the container where you place the form field. Add bg-white to the label, this should do the trick.

<div class="outline relative border-2 focus-within:border-blue-500">
  <input type="text" name="username" placeholder=" " class="block p-4 w-full text-lg appearance-none focus:outline-none bg-transparent" />
  <label for="username" class="absolute top-0 text-lg bg-white p-4 -z-1 duration-300 origin-0">Username</label>
</div>

Now you have the outline form field working too. 👍

Building a form

Now create a form using the outline style.

<form class="max-w-sm mx-auto rounded-lg shadow-xl overflow-hidden p-6 space-y-10">
  <h2 class="text-2xl font-bold text-center">Login</h2>
  <div class="outline relative border-2 focus-within:border-blue-500">
    <input type="text" name="username" placeholder=" " class="block p-4 w-full text-lg appearance-none focus:outline-none bg-transparent" />
    <label for="username" class="absolute top-0 text-lg bg-white p-4 -z-1 duration-300 origin-0">Username</label>
  </div>
  <div class="outline relative border-2 focus-within:border-blue-500">
    <input type="email" name="email" placeholder=" " class="block p-4 w-full text-lg appearance-none focus:outline-none bg-transparent" />
    <label for="email" class="absolute top-0 text-lg bg-white p-4 -z-1 duration-300 origin-0">Email</label>
  </div>
  <div class="outline relative border-2 focus-within:border-blue-500">
    <input type="password" name="password" placeholder=" " class="block p-4 w-full text-lg appearance-none focus:outline-none bg-transparent" />
    <label for="password" class="absolute top-0 text-lg bg-white p-4 -z-1 duration-300 origin-0">Password</label>
  </div>
</form>

If you followed along, create and customize your own floating form field w/ Tailwind CSS. Send me your own design on Twitter @mrcjln.

Migrate Git Repository to Git Large File Storage (LFS)

Marc Stammerjohann — Mon, 27 Apr 2020 16:30:01 +0000

If you ever come across this error while pushing an existing repository or a large file to GitHub…

remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com.

… here is how to setup Git Large File Storage (LFS) and migrate your Git history.

1. Download and Install Git LFS extension

Download and install the Git LFS extension, you can also install it using Homebrew.

brew install git-lfs

2. Setup Git LFS for your current user account

git lfs install

3. Select files to be managed by Git LFS

# track files by file type
git lfs track "*.zip"

# track directories by path
git lfs track "assets/*"

# track entire directory trees
git lfs track "assets/**/*"

# track file by path
git lfs track "path/to/file"

git lfs track will add the files tracked by Git LFS to .gitattributes. It is important to add .gitattributes to Git.

git add .gitattributes

Note : Tracking files are not automatically converting these files from your Git history or other branches.

4. Migrate Git History

If you have existing files in your Git history or in other branches you need to migrate those files to be tracked by Git LFS as well. Git LFS provides a command git lfs migrate with various options depending on your use case.

Before performing your migration you can perform a dry run with git lfs migrate info [options]. Use the option --everything to perform a migration in every branch. If you only want to migrate files you added before with git lfs track you will add those with the --include="*.zip,src/assets" flag comma separated.

Here is an example which performs a migration for all Zip-files.

# dry run of your migration
git lfs migrate info --everything --include="*.zip"

# perform migration
git lfs migrate import --everything --include="*.zip" --verbose

Now go ahead and push your repository to GitHub. If successfully pushed and setup GitHub displays the following tag for each file tracked by Git LFS.

How to manage multiple Java JDK versions on macOS X

Marc Stammerjohann — Thu, 16 Apr 2020 10:10:13 +0000

Here is a quick tip on how to install multiple Java JDK versions (8, …, 11, …, 14 etc.) on macOS X and how to switch between them for your applications.

Installing Java JDK via Homebrew

Install multiple Java JDK versions using Homebrew. To install Homebrew run:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

Now install the Java JDK version 11 or above using brew cask:

brew cask install java<version>

# latest version
brew cask install java

# LTS 11
brew cask install java11

Note JDK versions prior 11 ( 8 , 9 and 10 ) are no longer supported.

AdoptOpenJDK provides older Java versions. To install the Java JDKs from AdoptOpenJDK:

# install from third party repository
brew tap adoptopenjdk/openjdk

brew cask install adoptopenjdk<version>

# Java 8
brew cask install adoptopenjdk8

# Java 9
brew cask install adoptopenjdk9

# Java 10
brew cask install adoptopenjdk10

Switch Java JDK via alias

Setup your JAVA_HOME path in your .zshrc or .bash_profile for your primary Java version and add an export for each installed Java version.

export JAVA_HOME=$(/usr/libexec/java_home -v14)

export JAVA_8_HOME=$(/usr/libexec/java_home -v1.8)
export JAVA_11_HOME=$(/usr/libexec/java_home -v11)
export JAVA_14_HOME=$(/usr/libexec/java_home -v14)

To check the default Java version and installation path:

java -version # 14

Add an alias to your .zshrc or .bash_profile for each installed Java version. The alias exports JAVA_HOME with the selected JAVA_VERSION_HOME.

alias java8='export JAVA_HOME=$JAVA_8_HOME'
alias java11='export JAVA_HOME=$JAVA_11_HOME'
alias java14='export JAVA_HOME=$JAVA_14_HOME'

Now, to switch between the Java versions, enter an alias java8 in your terminal. Execute java -version to verify that you are now using the correct Java version.

Note : Alias only changes the Java version in the used terminal instance

GraphQL Code-First Approach with NestJS 7

Marc Stammerjohann — Tue, 31 Mar 2020 18:58:05 +0000

Recently the release of NestJS 7 was announced with amazing updates to the whole framework including the @nestjs/graphql ❤️ package.

We create a GraphQL API using the @nestjs/graphql. You will learn how to write the API with TypeScript using the code first approach and the new GraphQL plugin.

In this guide we are using Prisma to easily access a database. You can follow this guide to setup a Nest application with Prisma as Prisma is out of scope for this guide.

Setup GraphQL

To start a GraphQL API install the following packages into your Nest application.

npm i --save @nestjs/graphql graphql-tools graphql

# for Express
npm i --save apollo-server-express
# for Fastify
npm i --save apollo-server-fastify

Import the GraphQLModule into your AppModule.

import { Module } from '@nestjs/common';
import { GraphQLModule } from '@nestjs/graphql';
import { join } from 'path';

@Module({
  imports: [
    GraphQLModule.forRoot({
      autoSchemaFile: join(process.cwd(), 'src/schema.gql'),
      debug: true,
      playground: true
    })
  ]
})
export class AppModule {}

To configure the GraphQL endpoint we use GqlModuleOptions which are passed to the underlying GraphQL server. Here we are enabling the code first approach.

autoSchemaFile enables the code first approach to use TypeScript classes and decorators to generate the GraphQL schema.
playground enables the GraphQl Playground, an interactive IDE for your API documentation, available at http://localhost:3000/graphql.
debug mode

There are two options for autoSchemaFile providing a path for the schema generation or true for generating the schema in memory.

GraphQL Code First approach

A GraphQL schema contains many types and Queries. The schema grows in size and complexity for each new query, mutation and type. GraphQL Code First enables us to automatically generate a GraphQL schema using TypeScript and decorators. This helps us focus on writing .ts files and we don't need to write the GraphQL schema ourselves.

@nestjs/graphql provides all decorators to generate our schema. Here are a few decorators and there usage:

@ObjectType() generate class as Type
@Field() generate a class property as a Field
@InputType() generate class as Input
@Args generate method params as Arguments
@Query() generate method as Query
@Mutation() generate method as Mutation
@ResolveField resolve relationship property

Graphql Type

Start with creating your objects as a TypeScript class.

export class User {
  id: number;
  createdAt: Date;
  updatedAt: Date;
  email: string;
  password: string;
  name?: string;
  hobbies: Hobby[];
}

export class Hobby {
  id: number;
  name: string;
}

Let's add decorators to expose this model in our GraphQL schema. Start adding @ObjectType() to the TypeScript class.

import { ObjectType } from '@nestjs/graphql';

@ObjectType()
export class User {
  ...
}

@ObjectType()
export class Hobby {
  ...
}

Next we use the @Field decorator on each class property providing additional information about the type and state (required or optional).

import { ObjectType, Field, Int } from '@nestjs/graphql';

@ObjectType()
export class User {
  @Field(type => Int)
  id: number;

  @Field(type => Date, { name: 'registeredAt' })
  createdAt: Date;

  @Field(type => Date)
  updatedAt: Date;

  @Field(type => String)
  email: string;

  password: string;

  @Field(type => String, { nullable: true })
  name?: string;

  @Field(type => [Hobby])
  hobbies: Hobby[];
}

@ObjectType()
export class Hobby {
  @Field(type => Int)
  id: number;

  @Field(type => String)
  name: string;
}

The following GraphQL type is generated if this class is used in a resolver.

type User {
  id: Int!
  registeredAt: DateTime!
  updatedAt: DateTime!
  email: String!
  name: String
  hobbies: [Hobby!]!
}

@Field takes an optional type function (e.g. type => String)
Declare a field as an array using the bracket notation [] in the type function (e.g. type => [Hobby])
Optional FieldOptions object to change the generated schema
name: property name in the schema (createdAt => registeredAt)
description: adding a field description
deprecationReason: adding a deprecation notice
nullable: declare a field is required or optional
Hide properties from the schema by omitting @Field

For more details head over to the NestJS docs!

We have added a bit of boilerplate to our User model and other models we will create. Nest provides a CLI plugin to reduce the boilerplate of our models. Check out the GraphQL plugin section on how to reduce the boilerplate.

GraphQL Resolver

Great our models are in place! Now we use the Nest CLI to generate our resolvers.

nest generate resolver <name>

# alias
nest g r <name>

# User and Hobby
nest g r user
nest g r hobby

Our resolvers are added to the providers array in the app.module.ts.

import { Resolver } from '@nestjs/graphql';
import { User } from '../models/user.model';

@Resolver(of => User)
export class UserResolver {
  ...
}

Declare a of function in the @Resolver decorator (e.g. @Resolver(of => User)) this is used to provide a parent object in @ResolveField. We will cover @ResolveField in a bit.

Add @Query to your resolvers to create new GraphQL queries in your schema. Let's create a query function returning all users(). Use the bracket notation inside the decorator @Query(returns => [User]) to declare an array return value.

Note: Prisma is used in this example, but can be replaced easily with an ORM of your choice like TypeORM, Mongoose or Sequelize. See the full database setup in the example repo.

import { Resolver, Query } from '@nestjs/graphql';
import { User } from '../models/user.model';
import { PrismaService } from '../prisma/prisma.service';

@Resolver(of => User)
export class UserResolver {
  constructor(private prisma: PrismaService) {}

  @Query(returns => [User])
  async users() {
    return this.prisma.user.findMany();
  }
}

The above code generates the following query to our schema:

type Query {
  users: [User!]!
}

A User has a relation to many hobbies. To resolve the hobbies property from a user, we make use of the @ResolveField decorator. Add @ResolveField to a function with the exact same name of the property we want to resolve. Here we add a hobbies() function and provide a User object as the parent.

import { Resolver, Query, ResolveField, Parent } from '@nestjs/graphql';
import { User } from '../models/user.model';
import { PrismaService } from '../prisma/prisma.service';

@Resolver(of => User)
export class UserResolver {
  constructor(private prisma: PrismaService) {}

  @Query(returns => [User])
  async users() {
    return this.prisma.user.findMany();
  }

  @ResolveField()
  async hobbies(@Parent() user: User) {
    return this.prisma.hobby.findMany({
      where: { user: { id: user.id } }
    });
  }
}

Use the parent object to query the relationship object from a database or another endpoint.

Test GraphQL API

Start your Nest application and navigate to the playground, it is available if playground is set to true in the GraphQLModule.

The playground shows us our GraphQL schema and the docs for our queries.

Additionally, we can "play" with queries inside the playground. Try out the autocomplete feature in the playground to create your own queries based on your schema and queries.Let's query all users using the following query:

query AllUsers {
  users {
    id
    registeredAt
    updatedAt
    email
    name
    hobbies {
      id
      name
    }
  }
}

The response will look like this with a different data set. I prepared the database with a few dummy users and hobbies.

GraphQL plugin

Nest 7 provides a new GraphQL plugin to reduce the boilerplate of decorators for our models , inputs , args and entity files. Enable the plugin by adding compilerOptions to nest-cli.json:

{
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "plugins": ["@nestjs/graphql/plugin"]
  }
}

The plugin automatically handles the decorators for the files with the suffix ['.input.ts', '.args.ts', '.entity.ts', '.model.ts']. If you like to use custom suffixes add those to the plugins option:

"plugins": [
  {
    "name": "@nestjs/graphql/plugin",
    "options": {
      "typeFileNameSuffix": [".input.ts", ".model.ts"]
    }
  }
]

Let's clean up the boilerplate of our models. Before the plugin the models look like this:

import { ObjectType, Field, Int } from '@nestjs/graphql';
import { Hobby } from './hobby.model';

@ObjectType()
export class User {
  @Field(type => Int)
  id: number;

  @Field(type => Date, { name: 'registeredAt' })
  createdAt: Date;

  @Field(type => Date)
  updatedAt: Date;

  @Field(type => String)
  email: string;

  password: string;

  @Field(type => String, { nullable: true })
  name?: string;

  @Field(type => [Hobby])
  hobbies: Hobby[];
}

@ObjectType()
export class Hobby {
  @Field(type => Int)
  id: number;

  @Field(type => String)
  name: string;
}

After removing the extra boilerplate decorators the models looks like this:

import { ObjectType, Field, Int, HideField } from '@nestjs/graphql';
import { Hobby } from './hobby.model';

@ObjectType()
export class User {
  @Field(type => Int)
  id: number;

  @Field({ name: 'registeredAt' })
  createdAt: Date;

  updatedAt: Date;

  email: string;

  @HideField()
  password: string;

  name?: string;

  hobbies: Hobby[];
}

@ObjectType()
export class Hobby {
  @Field(type => Int)
  id: number;

  name: string;
}

Note: Hiding properties from the schema requires the @HideField decorator.

We can add @Field to any property to override the documentation and also the inferred type.For example number is inferred as the GraphQL type Float here we can use @Field(type => Int) to change this to an Int type.