Forem: beeman 🐝

Deploy a NestJS API to Heroku from a Nx Workspace

beeman 🐝 — Fri, 21 Aug 2020 03:48:50 +0000

Introduction

In this tutorial, we deploy the API to Heroku. First, the run-scripts build and start in package.json are configured and tested. After that, we use the Heroku CLI to create a new app under our account, and deploy the API.

Requirements

For this tutorial, you need:

An account on Heroku, sign up here if you don't have one.
- A free account is sufficient, and you don't need a credit card to get one!
The Heroku CLI, visit this page and follow the installation instructions.
- Run heroku -v to verify it's installed.

1. Configure and test the production build.

In this step, we run the build command locally to make sure everything works as expected.

1.1 Update the run-scripts in package.json

Open package.json and find the scripts object. Replace the values of the start and build scripts with the following commands:

  "scripts": {
    //...
    "start": "node dist/apps/api/main.js",
    "build": "nx build api --prod",
    //...
  },

1.2 Build and run the API locally

With these scripts in place, run the following command to build the API:

yarn build

The output will be similar to the following:

yarn run v1.22.4
$ nx build api --prod

> nx run api:build:production
Starting type checking service...
Using 14 workers with 2048MB memory limit
Hash: c521fa45a781fce8412b
Built at: 08/20/2020 10:02:15 PM
Entrypoint main = main.js main.js.map
chunk    {0} main.js, main.js.map (main) 4.15 KiB [entry] [rendered]
✨  Done in 9.95s.

Once the API has been built, run the following command to start the API:

yarn start

💡 Make sure to stop your development server before starting the API, because you can only have one process listening on the same port. If you forget that, the API will fail, and print message like this:

Error: listen EADDRINUSE: address already in use :::3000

1.3 Commit your changes

The Heroku deployments work by pushing a branch to the created application. That means that in order for the last changes to take effect, we need to commit the changes before we move on.

Run the following command to commit the changes:

git commit -am "Update run-scripts"

2. Deploy to Heroku.

In order to deploy the API to Heroku, we first create an application on Heroku. After that, we can use git push to actually deploy the API.

2.1 Create the application on Heroku

Run the following command to create the application on Heroku:

heroku create beehive-graphql

💡 The application name on Heroku has to be unique. If you use an existing name, Heroku will tell you:

Creating ⬢ beehive-graphql... !
 ▸    Name beehive-graphql is already taken

2.2 Deploy the application to Heroku

Run the following command to trigger the deployment on Heroku:

git push heroku master

This will push the latest commit to Heroku, and start the build process. You can follow the output in your terminal.

Once you get the following text, the application has been successfully deployed:

remote: https://beehive-graphql.herokuapp.com/ deployed to Heroku

2.3 Test the GraphQL API on Heroku

You can now visit the GraphQL endpoint on your newly deployed API:

Visit https://beehive-graphql.herokuapp.com/graphql to check it out!

However, what you see now not the playground you saw in the previous tutorial 😲.

GET query missing.

The reason is that the API on Heroku runs in production mode, and this disabled playground the playground by default.

Luckily, we can use a curl command to verify the API is working

Run the following command to execute the uptime query:

curl -XPOST \
     -H "Content-Type: application/json" \
     --data ' { "query": "query { uptime }"  }' \
     https://beehive-graphql.herokuapp.com/graphql

2.4 Enable the Playground on production servers (optional)

Sometimes it can be useful to deploy a GraphQL server with the playground enabled in production mode.

In order to do so, open libs/core/src/lib/core.module.ts and change the configuration of the GraphQLModule, and set the playground option to true:

GraphQLModule.forRoot({
  autoSchemaFile: true,
  playground: true,
}),

In order to deploy this, commit the changes and run the deployment again:

git commit -am "Enable playground in Production mode"
git push heroku master

When you now visit https://beehive-graphql.herokuapp.com/graphql, you should be greeted with the playground again! 🎉

Summary

In this tutorial, we configured the start and build run-scripts in package.json and made sure they worked as expected. We committed those changes in order for them to be pushed to Heroku.

After that, we created a new application on Heroku and used the git push command to deploy the API.

Because Heroku runs the apps in production by default, we did not get the GraphQL Playground when visiting the /graphql endpoint on the API. Luckily, this is easy to fix by enabling the playground option in the GrapQLModule.

Thanks!

And with that, this series comes to an end, I hope it was useful. If you want to see more content like this, make sure to follow me on Twitter. If you have any questions, send me a tweet or leave a comment on DEV! Cheers! 🐝

Add GraphQL to a NestJS API in a Nx Workspace

beeman 🐝 — Thu, 20 Aug 2020 03:51:07 +0000

Introduction

In this tutorial, we add GraphQL functionality to the API using the @nestjs/graphql package.

GraphQL is a specification for a strongly-typed query language for API's, and is well-supported by NestJS. If you're not familiar with GraphQL you can read this introduction.

1. Install and configure the @nestjs/graphql package.

In order to use GraphQL, we need to install the dependencies and configure the GraphQLModule.

1.1 Install the dependencies

yarn add @nestjs/graphql graphql-tools graphql apollo-server-express

We install the apollo-server-express dependency because NestJS uses express by default. Next to Express there is also support for Fastify.

1.2 Import the Module

Open libs/core/src/lib/core.module.ts and add the following lint on the top:

import { GraphQLModule } from "@nestjs/graphql";

Next, add the GraphQLModule to the imports array in the Module decorator:

@Module({
  imports: [
    // The ConfigModule lives here
    GraphQLModule.forRoot({
      autoSchemaFile: true
    })
  ]
  // The controllers, providers, exports arrays live here.
})
export class CoreModule {}

To initialize the GraphQLModule, we invoke the forRoot() method and pass it an object with the property autoSchemaFile set to true.

Setting autoSchemaFile set to true enables the code-first approach, which means that we can define our GraphQL schema by writing TypeScript classes with decorators, and NestJS will generate the actual GraphQL schema file based on that.

2 Add a Resolver

When you restart the dev server, you will get an error:

GraphQLError: Query root type must be provided.

This is because a GraphQL server must have at least one Query defined, and currently we have none. Time to add one and make the server run again!

2.1 Implement the CoreResolver

Create the file libs/core/src/lib/core.resolver.ts and add the following snippet:

import { Float, Query, Resolver } from "@nestjs/graphql";

@Resolver()
export class CoreResolver {
  @Query(() => Float)
  uptime() {
    return process.uptime();
  }
}

This class, that is decorated with the @Resolver() decorator, that has two functions:

It defines which GraphQL queries exists, and what type these queries returns.
It defines which code to execute when this query is invoked.

The queries can be defined by adding the @Query decorator to a method. The decorator will, by default, use the name of the method that is decorated, so our first query is called uptime. Inside the decorator is an anonymous function that returns the type, in our case this is a Float.

Inside the method body we simply return process.uptime(), which returns the uptime of the server.

💡 Make sure to import the Query decorator from the @nestjs/graphql package. The @nestjs/common package also exports a Query decorator, but that one is uses for REST API's.

2.2 Provide the CoreResolver in the CoreModule

Open libs/core/src/lib/core.module.ts and add the following lint on the top:

import { CoreResolver } from "./core.resolver";

Next, add the CoreResolver to the providers array in the Module decorator:

@Module({
  // The imports and controllers live here
  providers: [CoreResolver]
  // The exports live here
})
export class CoreModule {}

With this in place, the server should start again!

Visit http://localhost:3000/graphql to load the GraphQL Playground.

To test it, add the following query in the left-hand panel and click the Play button. The output should be similar to what you see in the screenshot.

query {
  uptime
}

Summary

In this tutorial, we added support for GraphQL to our API.

After installing the dependencies, we configured the GraphQLModule in the CoreModule.

Because a GraphQL server always needs at least one query, we implemented a resolver called CoreResolver and exposed a simple query called uptime.

To verify that this all worked, we launched the playground and tested the query.

In the next tutorial, the last one of this series, we will expose our server to Heroku! Stay tuned!

Thanks!

Thanks for reading my article, I hope it was useful. Feel free to reach out and follow me on Twitter or leave a comment on DEV! 🐝

Add a NestJS API to a Nx Workspace

beeman 🐝 — Fri, 07 Aug 2020 05:03:17 +0000

Introduction

In this tutorial, we add two projects to the workspace, an application called api, and a library called core.

In this app, the Core library is responsible for providing the application-wide configuration using the @nestjs/config package. To validate the configuration we configure NestJS Config to use Joi.

1. Add the Nx Nest plugin.

Nx has a plugin system that provides functionality for various frameworks. There are official ones and community plugins. One of the official ones is the Nest plugin.

Run the following command to install the plugin:

yarn add -D @nrwl/nest

This plugin provides functionality to create Nest applications and libraries. Let's start with the application.

2. Create the API.

In this step we create an application called api.

2.1 Generate the api application

Run the following command to create the application:

nx generate @nrwl/nest:app api

This generates a new application in apps/api, and adds it as a project to workspace.json and nx.json.

2.2 Start the dev server

Run the following command to start the application

nx serve api

This starts the development server and the prints the message 'Listening at http://localhost:3333/api'.

When you open that URL in the browser, you are greeted with the following message:

{
  "message": "Welcome to api!"
}

3. Create the core library

One of the great things of building an app using Nx Workspace, is that you can separate the functionality of the app into libraries.

This has numerous benefits: it creates a separation of concerns, it allows members of a team to work on parts of the app in isolation with less risk of conflicts, and allows for re-using the libraries in other projects.

3.1 Generate the library

Run the following command to create the library:

nx generate @nrwl/nest:lib core

This generates a new library in libs/core, adds it as a project to workspace.json and nx.json.

Additionally, it adds an entry to the paths object in tsconfig.base.json, mapping the name @beehive/core to path libs/core/src/index.ts. This allows for using the library by importing it from the package name @beehive/core.

3.2 Use the library

Open apps/api/src/app/app.module.ts and add the following line on top, next to the other imports:

import { CoreModule } from "@beehive/core";

Next, add the CoreModule to the imports array in the @Module decorator:

@Module({
  imports: [CoreModule],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

Make sure to stop and start the dev server, so it will pick up the changes made in tsconfig.base.json.

When the server restarts, you should see that it loads the CoreModule:

[InstanceLoader] CoreModule dependencies initialized

💡 If you don't restart the dev server, it will not pick up the changes made in tsconfig.base.json and you will get an error like this:

ERROR in ./apps/api/src/app/app.module.ts
Module not found: Error: Can't resolve '@beehive/core'

Time to add some functionality to the core library.

4. Add the configuration.

4.1 Install the dependencies

Run the following command to install the dependencies and devDependencies:

yarn add @nestjs/config joi

4.2 Create the configuration file

Create the directory libs/core/src/lib/config, this is where the configuration is stored.

Next, create the file libs/core/src/lib/config/configuration.ts, and add the following snippet:

export const configuration = () => ({
  environment: process.env.NODE_ENV,
  port: parseInt(process.env.PORT || "3000", 10),
});

This file exports a method that returns an object with the configuration for the API.

The configuration object reads the values from the environment variables. Because environment variables are always represented as a string, the port property converts the value to an integer using parseInt.

Because the process.env.PORT variable can be undefined, the default string '3000' is provided. Leaving this out will make TypeScript's strict mode unhappy.

4.3 Create the validation file

Create the file libs/core/src/lib/config/validation.ts and add the following snippet:

import * as Joi from "joi";

export const validationSchema = Joi.object({
  NODE_ENV: Joi.string().valid("development", "production", "test").required(),
  PORT: Joi.number().default(3000),
});

The validation file exports a schema that uses Joi for validating the environment variables.

The PORT environment variable validates that the type is a number, and sets the default value.

For the NODE_ENV environment variable, the valid options are either development, production or test. We don't provide a default which means we should always apply one explicitly.

4.4 Tying it all together

Open libs/core/src/lib/core.module.ts and add the following imports at the top:

import { ConfigModule } from "@nestjs/config";
import { configuration } from "./config/configuration";
import { validationSchema } from "./config/validation";

After that, add a new array called imports to the @Module decorator, and add the ConfigModule like so:

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      load: [configuration],
      validationSchema,
    }),
  ],
  controllers: [],
  providers: [],
  exports: [],
})
export class CoreModule {}

When you have the server still running, the following error will appear:

Error: Config validation error: "NODE_ENV" is required

This is because we did not provide a default value for the NODE_ENV environment variable, which is required.

4.5 Add a .env file for development.

The Nest Config module uses dotenv under the hood. This means we can configure the environment using a .env file.

Create a new file called .env in your project root, and add the following snippet:

NODE_ENV=development
PORT=3000

Restart the dev server to make it read the .env file.

4.6 Update the .gitignore

Best practice is to not commit the .env file into git, as it might store sensitive information like API keys or database connections strings.

Open .gitignore from your project root and add the following line:

.env

💡 Because we don't include the .env file in the repository, it's considered a 'best practice' to provide a default .env.example file that can be used as a reference.

5. Use the configuration object.

Last thing to do is use the configuration in our api.

Open apps/api/src/main.ts and add the following imports at the top:

import { ConfigService } from "@nestjs/config";

Next, in the body of the bootstrap function, add the following to the start of the method, right below the definition of const app:

const app = await NestFactory.create(AppModule);
const config = app.get(ConfigService);

Lastly, we update the method of the listen method, and create a new line that invokes Logger.log, below the existin gone:

Logger.log("Listening at http://localhost:" + port + "/" + globalPrefix);
Logger.log(`Running in ${config.get("environment")} mode`);

When you start the dev server again, the following lines should appear in the output:

Listening at http://localhost:3000/api
Running in development mode

Awesome, the system works!

Summary

In this tutorial we created a Nest application called api, and a module called core.

The module is responsible for the application configuration and provides validation to make sure the required properties are defined and have the expected value.

We created a .env so we can easily apply environment vars during development, and added this file to .gitignore.

Lastly, we updated the main.ts file to make it use the ConfigService.

In the next tutorial, we will add a GraphQL endpoint to our API, stay tuned!

Thanks!

Thanks for reading my article, I hope it was useful. Feel free to reach out and follow me on Twitter or leave a comment on DEV! 🐝

Set up and configure a new Nx Workspace

beeman 🐝 — Thu, 06 Aug 2020 04:50:17 +0000

Introduction

In this tutorial, you learn how to set up and configure a Nx Workspace. Read the introduction to learn more about Nx Workspace.

We use the create-nx-workspace package to scaffold a new project. After that, we adjust the prettier settings to our liking, and add lint-staged and husky to make sure our code gets properly formatted on commit.

Requirements

For this tutorial, you need:

Node.js, visit the homepage for installation instructions.
- Run node -v to verify you have version 12 or higher.
Yarn (the classic version), visit the homepage for installation instructions.
- Run yarn -v to verify you have version 1.22.0 or higher (in the 1.x range).

1. Set up new project.

In this step we create a new project using the create-nx-workspace package on npm. The name of the project in this tutorial is beehive which will also be the npm scope of the packages that are created.

1.1 Create Workspace

Run the following command in your terminal to create a new workspace with the name beehive:

yarn create nx-workspace beehive

The installer asks a few questions, we provide the following options:

Create an empty workspace, we will add a custom structure.
Select the Nx CLI.
Answer Yes to enable Nx Cloud.

This generates a new workspace in the beehive directory.

Run the following command to enter the project root:

cd beehive

💡 All the following commands in this series will be executed from this directory, unless explicitly stated otherwise.

1.2 Create and add GitHub repo

Navigate to github.com/new, add a repository name like tutorial-nestjs-apis-with-nx, select either private or public and click Create Repository.

We are importing an existing repository, so be sure to not select any of the options below the line Skip this step if you’re importing an existing repository.

After that we land on the page of the new repository. Look for the commands in the second block on the page that says, ...or push an existing repository from the command line.

Execute the commands and in your terminal:

git remote add origin git@github.com:beeman/tutorial-nestjs-apis-with-nx.git
git push -u origin master

After this is done, switch back to the browser and refresh the page to verify the empty workspace is push to GitHub.

2. Configure Prettier

When creating a new Nx Workspace, it comes with support for Prettier out of the box. Let's adjust the default settings so that the formatting is done in line with our other projects.

💡This step is not essential, but it's very likely that you have some preference on how Prettier is formatting your code. Check this page to see what options are available.

2.1 Update the Prettier configuration

Open the project in your editor, then open the file .prettierrc.

Update the content with the settings you prefer or use my default options:

{
  "singleQuote": true,
  "printWidth": 120,
  "semi": false,
  "trailingComma": "all",
  "arrowParens": "always"
}

2.2 Re-format your code with the new settings

Once we have that in place, it's time to format the project with these settings.

In your terminal, run the following command:

nx format:write --all

💡 As the output suggest, because of performance it is not recommended running this command with the --all flag in larger projects. However, our project is empty and with the auto-formatting in place our project should always be properly formatted.

3. Set up automatic formatting on commit

To make sure the formatting gets applied consistently for each contributor of the project, it makes sense to have auto-format the code on each commit. With this in place we can be sure formatting is not dependent on whatever extensions the contributors might have installed in their editors.

To achieve this, we use the tools husky and lint-staged. The first one, husky, is a tool that allows you to define hooks on various git commands, we will be using the pre-commit hook. The second one, lint-staged, is a tool that runs commands like linters (or formatters in our case) on the files that are staged by git.

3.1 Add the dependencies

Run the following command to install these packages as dev-dependency:

yarn add -D husky lint-staged

3.2 Configure husky

Open package.json and add a new the following object on the top-level (for example, right below the devDependencies object):

"husky": {
  "hooks": {
    "pre-commit": "lint-staged"
  }
}

This configures husky to run the command lint-staged before each commit.

3.3 Configure lint-staged

Open package.json and right below your husky configuration, add the following:

"lint-staged": {
  "*.{js,json,css,scss,md,ts,html,graphql}": [
    "yarn format --uncommitted"
  ]
}

With this in place, when lint-staged runs, it will look for any of the extensions defined in the configuration, and execute the command yarn format --uncommitted.

4. Commit changes and push

With all this in place, the basic project is ready.

Run the following command to add the files commit and push:

git add .
git commit -m "configure prettier, husky and lint-staged"

When you run the commands above, you should see husky kicking in, which executes lint-staged which in turn formats your code.

Run the following command to push to GitHub

git push

Conclusion

In this tutorial, we created a new Nx Workspace and set it up with some tools to help us keep the project neat and clean.

We configured Prettier to our liking. After that, we installed husky and lint-staged and configured them in our package.json. After adding the files and committing them, we verified that we say these tools do their job.

In the next tutorial, we will add the Nest API to our project, stay tuned!

Thanks!

Thanks for reading my article, I hope it was useful. Feel free to reach out and follow me on Twitter or leave a comment on DEV! 🐝

Introduction to Building API's with NestJS and Nrwl Nx

beeman 🐝 — Wed, 05 Aug 2020 14:34:12 +0000

Introduction

In this tutorial, you learn how to build API's with NestJS and Nx Workspace. The goal is to give you a nice starting point that's easy to extend. Additionally, it will serve as a reference for later posts and series that I intend to write.

This post serves as an introduction to the technology stack and goes over the tutorials in the series.

NestJS

NestJS is a framework for building API's using Node.js and TypeScript. NestJS provides an opinionated API on top of Express (or optionally Fastify) and makes heavy use of TypeScript classes and decorators, enabling a declarative way to quickly add new functionality without writing a lot of code.

NestJS has great documentation and is actively maintained. There are a lot of useful libraries provided by the project itself, and there is a growing community that provides even more functionality. Besides that, NestJS is easy to extend if the functionality you need does not exist.

NestJS concepts

Here are a few NestJS concepts you should be aware of when going through this series.

Modules

The architecture from NestJS is inspired by Angular. It uses modules to encapsulate functionality in standalone, reusable blocks that can be imported by other modules. Modules tie the other components together, and make sure dependency injection works.

Controllers

The Controllers are used to build a RESTful API. They allow building any HTTP api that you can dream of, and does so in a clean and declarative matter by adding methods to TypeScript classes, and decorate them. These Controllers define the external REST API, most of the heavy lifting is done through Providers.

Providers

The Providers are injected into the Controllers, Resolvers or other Providers, and handle their requests. Things like accessing a database or calling into third-party API's or libraries are all done in Providers. This keeps the Controllers clean and focussed, and makes it easy to share the functionality with other parts of the application.

Resolvers

The Resolvers are used to build a GraphQL API. They allow building a GraphQL API using a code-first approach. That means that you don't need use GraphQL's Schema Definition Language (SDL) to define the API, but rather TypeScript code. Like the controllers, the Resolvers define the external API, and use Providers to do the heavy lifting.

Nx

Nx combines a mono-repository structure with CLI tools to develop and manage one or more applications and libraries, all within the same repository. Nx encourages code collaboration, unified testing, and optimizes builds and testing performances.

Nx is an amazing tool for building medium or large sized applications. Using a mono-repo allows you to easily share code between various parts of the project, without having to worry about the these parts being out of sync. Nx is smart in the sense that it knows which parts of the app relate to each other. Read more about the Dependency Graph below.

Nx concepts

Here are a few Nx concepts you should be aware of when going through this series.

Workspace

The workspace is defined on the root of the repository, and consists of one or more projects, which can be either an application or a library. The workspace uses either the Nx CLI or Angular CLI to serve, test, build and lint the projects. The workspace is defined in the files nx.json and workspace.json (or angular.json if using the Angular CLI).

Applications

In Nx, the applications (or apps), are the projects that contain a runnable application. Applications should be light-weight, and expose the functionality defined in the libraries.

Libraries

The libraries (or libs), are the projects that implement the functionality for the apps. The libraries define an external API that can be consumed by the apps and other libs.

Plugins

The actual functionality of the Nx workspace is defined by the plugins that are installed. Nx comes with quite a few official plugins that add support for, for example, Angular, Node, Next, React and Web Components. Additionally, there is a growing list of community plugins.

Dependency Graph

The Dependency Graph, or dep graph, is an automatically generated schema that shows how different parts of the monorepo depend on each other. Nx uses this information to intelligently execute commands on parts of the workspace. For example, it will only re-build projects that are actually changed, or when one of the dependencies are change.

The project structure

In this series though, we use a simple structure. We build an app called api that consumes the libraries core and course, like this:

apps/api
libs/core
libs/course
libs/<library> (any other functionality goes here).

Tutorial in this series

This series consists of four tutorials that, when finished, result in a project that is solid basis that's easy to extend.

Set up and configure a new Nx Workspace

To start the project, we create an empty Nx Workspace and take a look around to see what it consists of. We install and configure some tools to automatically format the code on each commit. Having this in place makes sure all future code has a similar style.

Add a NestJS API to a Nx Workspace

After creating the project, we use the official NestJS plugin for Nx to create an application called api with a library called core. The core library is responsible for exporting the runtime configuration, and is consumed by the api.

Add GraphQL to a NestJS API in a Nx Workspace

When these parts are in place, we move on to adding actual functionality to the api. After installing the needed dependencies and configure the GraphQL Module for NestJS, we implement a GraphQL resolver and add a simple query that returns the servers' uptime.

Deploy a NestJS API to Heroku from a Nx Workspace

Once this is all done, the API is ready to ship! After building the project locally and making sure it all works as expected, we add the configuration to deploy it to Heroku.

Thanks!

First of all, thanks to the reviewers of this series 🙏:

The cover photo for this series is an edited version of this photo by Todd Kent on unsplash.

Thank YOU for reading my article, I hope it was useful. Feel free to reach out and follow me on Twitter or leave a comment on DEV! 🐝

Using oclif to create a CLI for the DEV API

beeman 🐝 — Thu, 09 Jul 2020 02:42:53 +0000

In this tutorial, you learn how to use oclif to create a CLI that lists the articles in your DEV account.

The goal is to show how to create a CLI that interacts with an authenticated API. We will only add one single command, (list), however extending the CLI should be pretty straightforward.

This tutorial documents the first steps I took when I built dev-to-sync, take a look at that repo to see how I added some more commands.

Requirements

Node.js and NPM, visit the homepage for installation instructions.
- Run node -v to verify you have version 12 or higher.
- Run npm -v to verify you have version 6 or higher.
A DEV API key
- Generate one here https://dev.to/settings/account.

Install the oclif cli

npm install -g oclif

Setup a new project

oclif multi dev-to-sync
cd dev-to-sync

Initialize git repo

Even though it's not essential for the working of the CLI, you probably want to initialize a git repo and do an initial commit.

git init
git commit -m "Initial commit"

Link local project

In order to make our new CLI available for running it locally while we're developing it, it needs to be linked:

npm link

Run it

Now that that's done, we can give it a run to see if it all works.

If all went well, running the command dev-to-sync should output something like this:

$ dev-to-sync
Sync your DEV account with a local folder

VERSION
  dev-to-sync/0.0.0 darwin-x64 node-v12.18.1

USAGE
  $ dev-to-sync [COMMAND]

COMMANDS
  hello  describe the command here
  help   display help for dev-to-sync

This shows us there is a hello command, which we can execute like this:

$ dev-to-sync hello
hello world from ./src/commands/hello.ts

Creating alias

In this step we give our CLI a shortcut dts so we can invoke it with less keystrokes.

Open package.json and add a key dts with value ./bin/run to the bin object.

  "bin": {
    "dev-to-sync": "./bin/run",
    "dts": "./bin/run"
  }

After this you need to run npm link again to make sure your operating system is aware of the new command.

Create a wrapper for the DEV api

To access the DEV api we create a wrapper class called DevtoClient. We initialize the class with the API key and use that to set up the header, adding the api-key property to each request.

We implement a get method to execute authenticated requests to the DEV api and a getArticles method that retreives the articles.

Install the dependencies

Install node-fetch and it's types:

npm install node-fetch
npm install -D @types/node-fetch

Create the client

Create src/lib/devto-client.ts and add the following snippet:

import fetch from "node-fetch";

export class DevtoClient {
  private readonly baseUrl = "https://dev.to/api";

  private readonly headers: { "api-key": string; "content-type": string };

  constructor(private readonly apiKey: string) {
    this.headers = {
      "api-key": this.apiKey,
      "content-type": "application/json",
    };
  }

  get(url: string) {
    return fetch(this.baseUrl + url, { headers: this.headers }).then((res) =>
      res.json()
    );
  }

  async getArticles(): Promise<any[]> {
    const result = await this.get("/articles/me/all");

    if (!result) {
      throw new Error("Error retrieving articles");
    }
    return result;
  }
}

Create src/lib/utils.ts and add the following snippet:

import { DevtoClient } from "./devto-client";

if (!process.env.DEV_TO_TOKEN) {
  throw new Error(`Environment variable DEV_TO_TOKEN not found`);
}

export const client = new DevtoClient(process.env.DEV_TO_TOKEN);

We now can import the client at any of the commands and use it.

Implementing the list command

Create the command

Run the following command to create a new command to the CLI:

oclif command list

Implement the command

Open src/commands/list.ts and replace the content with the following snippet:

import { Command } from "@oclif/command";
import { client } from "../lib/utils";

export default class List extends Command {
  static description = "List articles in a DEV account";

  async run() {
    const articles = await client.getArticles();

    for (const article of articles) {
      console.log(article.title);
    }
  }
}

Test the command

$ dts list
Tutorial: Styling Angular CLI Apps with Bootstrap
Automate your DEV Posts using GitHub Actions
Using yarn with Angular CLI

Where to go from here?

This should be a steady basis to quickly build more functionality. You can, for example:

Use oclif command to add more commands, check the DEV api documentation for the available API methods.
Add colors to the output using chalk.
Make the CLI interactive using inquirer.
Use oclif plugins if you want to add additional functionality to your CLI like autoupdate, autocomplete or update warnings.
Download beeman/dev-to-sync for a more complete implementation.

Conclusion

In this tutorial, we created a CLI from scratch by using oclif. After setting up the project, we implemented an API client that communicates with the DEV api, and a small method that wraps the API client and takes the API key from the environment. The last step was implementing the list command to retrieve the articles from the list, and show them in the console.

Thanks!

Thanks for reading my article. Feel free to reach out if you have any questions! Follow me on Twitter or leave a comment on DEV! 🐝

Tutorial: Styling Angular CLI Apps with Bootstrap

beeman 🐝 — Tue, 07 Jul 2020 17:20:22 +0000

In this tutorial, you learn how to use Bootstrap to style Angular CLI Apps.

The goal is to build an application layout with a header and footer, a home page, about page, and a login page with form.

Check the live demo here or the GitHub repo.

Requirements

Make sure you have the following tools installed:

Node.js and NPM, visit the homepage for installation instructions.
- Run node -v to verify you have version 12 or higher.
- Run npm -v to verify you have version 6 or higher.
Angular CLI (npm install -g @angular/cli@latest to install)
- Run ng --version to verify you have version 10 or higher.

If you prefer using yarn, first configure Angular CLI's default package manager. This makes sure the generated application has a yarn.lock file instead of a package-lock.json.

1. Create a new application

Open a terminal and run the following command:

ng new sandbox --routing --style scss --strict

The ng new command generates a basic Angular application in a directory called sandbox and installs the dependencies.

The --routing flag instructs Angular CLI to generate a routing module.
The --style scss parameter sets SCSS as the style preprocessor.
The --strict flag configures the application to run in strict mode.

At the end of the setup, the Angular CLI also initializes a git repository and does an initial commit.

2. Start the application in development mode

After the installation is finished, run the following command to navigate to the project directory.

cd sandbox

In the project directory you can start the development server using ng serve:

ng serve

** Angular Live Development Server is listening on localhost:4200, open your browser on http://localhost:4200/ **

Navigate to the link displayed by the Dev server and verify that it works. The app is now ready to get some style(s)! 😎

3. Install Bootstrap

Run the following command in your project directory to install Bootstrap:

npm install bootstrap

When the installation is finished we now can tell Angular CLI to use these styles.

Open src/styles.scss and add the following lines:

@import '~bootstrap/scss/bootstrap';
// Set the full page height so we can stick the footer to the bottom
html,
body {
  height: 100%;
}

Next, open src/app/app.component.html and delete all the content, replace it with the following snippet:

<h1 class="text-center text-primary">Hello Bootstrap!</h1>

When you go back to your browser, you should see Hello Bootstrap in big blue letters! 🎉

Let's move on to make our app look a little better!

4. Configure the application layout

In this step we create a UiModule and add three components to it: LayoutComponent, HeaderComponent and FooterComponent.

💡 It's a good idea to keep the UI separate from the rest of the app. This 'separation of concerns' also allows you to easily re-use the UI in other projects.

4.1 Create the `UiModule`

Run the following command to generate the UiModule.

ng generate module ui --module app

The --module parameter imports the UiModule in our main AppModule:

Next, generate the 3 components inside of this new module:

ng generate component ui/layout
ng generate component ui/header
ng generate component ui/footer

💡 The ng generate command supports shortcuts: use ng g c to generate a component, ng g m to generate a module, etc.

4.2 Implement the LayoutComponent

Open src/app/ui/layout/layout.component.html replace the content with the following snippet:

<!-- This flex container takes the full height -->
<div class="d-flex flex-column h-100">
  <app-header></app-header>
  <!-- The main area does not shrink, 'pushing down' the footer -->
  <main class="flex-shrink-0">
    <!-- This will render the routes -->
    <router-outlet></router-outlet>
  </main>
  <!-- This keeps the footer down if the main content does not fill up the space -->
  <footer class="mt-auto">
    <app-footer></app-footer>
  </footer>
</div>

We use this LayoutComponent in the router, and render the children in the location of router-outlet.

Before moving on, make sure to import RouterModule in UiModule.

Open src/app/ui/ui.module.ts and add the following code next to the other imports:

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

Add RouterModule to the imports array:

@NgModule({
  declarations: [LayoutComponent, HeaderComponent, FooterComponent],
  imports: [CommonModule, RouterModule],
})

💡 If you forget to import the RouterModule, the server will tell you:

ERROR in src/app/ui/layout/layout.component.html:3:3 - error NG8001: 'router-outlet' is not a known element:
  1.  If 'router-outlet' is an Angular component, then verify that it is part of this module.
  2.  If 'router-outlet' is a Web Component then add 'CUSTOM_ELEMENTS_SCHEMA' to the '@NgModule.schemas' of this component to suppress this message.</pre>

4.3 Use the LayoutComponent

Open src/app/app-routing.module.ts and replace the line const routes: Routes = [] with the following snippet:

const routes: Routes = [
  {
    path: '',
    component: LayoutComponent,
    children: [
      // Here we will add our application pages
    ],
  },
];

Make sure to import LayoutComponent in src/app/app-routing.module.ts:

import { LayoutComponent } from './ui/layout/layout.component';

Open src/app/app.component.html and replace the content with the following snippet:

<router-outlet></router-outlet>

Save all the files and check your browser, you should see the default HeaderComponent and FooterComponent being rendered. Time to spice them up!

4.4 Implement the Header

Open src/app/ui/header/header.component.html and replace the content with the following snippet:

<!-- You can change the values `dark` here with any of the following: -->
<!-- dark, light, primary, secondary, success, info, danger, warning -->
<nav class="navbar navbar-dark bg-dark">
  <!-- This is the application title with a link to the root -->
  <a class="navbar-brand" routerLinkActive="active" routerLink="/">Angular & Bootstrap</a>
  <!-- This is a spacer so the links move to the end -->
  <div class="mr-auto"></div>
  <!-- This main navigation links are defined here -->
  <div class="navbar-expand">
    <div class="navbar-nav">
      <!-- Each link has the routerLink property set to a different route -->
      <a class="nav-item nav-link" routerLinkActive="active" routerLink="/home">Home</a>
      <a class="nav-item nav-link" routerLinkActive="active" routerLink="/about">About</a>
      <a class="nav-item nav-link" routerLinkActive="active" routerLink="/login">Login</a>
    </div>
  </div>
</nav>

Refer to the bootstrap documentation of the navbar for more details on the syntax of the navbar and how to make it responsive.

4.5 Implement the Footer

Open src/app/ui/footer/footer.component.html and replace the content with this:

<div class="py-3 bg-dark text-center text-muted">
  <small>Copyright &copy; 2020</small>
</div>

5. Add application Pages

With the application layout in place, it's time to add a few pages.

The command we use creates a module with a component and lazy-loads it in the AppModule.

💡 Lazy loading is the recommended way of routing in an Angular app as it makes sure the users don't download any code they won't run.

5.1 Create a Home page

Run the following command to generate the HomeModule:

ng g module pages/home --route home --module app

Open src/app/pages/home/home.component.html and replace the content with this:

<div class="container py-5">
  <div class="jumbotron">
    <h1 class="text-secondary">Home</h1>
  </div>
</div>

Go to your application in the browser and click the Home link in the header.

You will be taken to the route /home with the text 'Home'. However, the layout with the header and footer is gone!

To fix this, open src/app/app-routing.module.ts and move the newly created route inside the children array:

const routes: Routes = [
  {
    path: '',
    component: LayoutComponent,
    children: [
      // Here we will add our application pages
      {
        path: 'home',
        loadChildren: () => import('./pages/home/home.module').then(m => m.HomeModule),
      },
    ],
  },
];

After saving this file, the page should render properly.

5.2 Create an About page

Run the following command to generate the AboutModule:

ng g module pages/about --route about --module app

Open src/app/pages/about/about.component.html and replace the content with this snippet:

<div class="container py-5">
  <div class="jumbotron">
    <h1 class="text-secondary">About</h1>
  </div>
</div>

Open src/app/app-routing.module.ts and move the about route inside the children, so it sits next to the route to the HomeModule.

5.3 Create a Login page

The login page is a bit more complex because it has a form and uses the router to redirect.

Run the following command to generate the LoginModule:

ng g module pages/login --route login --module app

Open src/app/pages/login/login.component.ts and add the following code next to the other imports:

import { FormControl, FormGroup } from '@angular/forms';
import { Router } from '@angular/router';

Change the content of the LoginComponent class to this snippet:

export class LoginComponent implements OnInit {
  // The form group defines the fields used in the form
  form = new FormGroup({
    email: new FormControl(''),
    password: new FormControl(''),
  });

  // Inject the router so we can navigate after a successful login
  constructor(private readonly router: Router) {}

  ngOnInit(): void {}

  public submit() {
    // Use the form value to do authentication
    console.log(this.form.value);
    // Navigate after successful login
    return this.router.navigate(['/']);
  }
}

Open src/app/pages/login/login.component.html and replace the content with this snippet:

<!-- This flex container takes the full height and vertically centers the content -->
<div class="d-flex flex-column h-100 justify-content-center">
  <div class="container">
    <div class="row">
      <!-- This is a single column that is responsive -->
      <div class="col-12 col-md-6 offset-md-3">
        <div class="card">
          <div class="card-header">Login</div>
          <div class="card-body">
            <!-- The formGroup 'form' is defined in the component class -->
            <form [formGroup]="form">
              <div class="form-group">
                <label for="email">Email address</label>
                <!-- The formControlName defines the name of the field in the formGroup -->
                <input id="email" formControlName="email" type="email" required class="form-control" />
              </div>
              <div class="form-group">
                <label for="password">Password</label>
                <input id="password" formControlName="password" type="password" required class="form-control" />
              </div>
            </form>
          </div>
          <div class="card-footer">
            <div class="d-flex justify-content-between">
              <a routerLink="/" class="ml-2 btn btn-outline-secondary">
                Home
              </a>
              <!-- The button has a click handler, it will be disabled if the form is not valid -->
              <button (click)="submit()" [disabled]="!form.valid" type="submit" class="btn btn-outline-success">
                Log in
              </button>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
</div>

💡 The template of the LoginComponent is quite large. When adding more authentication pages, consider creating a separate AuthLayoutComponent and use that like LayoutComponent, then add LoginComponent, RegisterComponent, etc as the children of AuthLayoutComponent.

Go to your application in the browser and click the Login link in the header.

The login page renders the form in the center of the screen, and we don't need to add the route to the children array.

There is one last thing to fix. If you click the Home link in the login page, you will be taken back to the root of the application, which is blank.

Wouldn't it be great if we could go to the Home page instead?

5.4 Redirect the root route

Open src/app/app-routing.module.ts and add the following object on the top of the routes array:

const routes: Routes = [
  {
    path: '',
    // If this path is the 'full' match...
    pathMatch: 'full',
    // ...redirect to this route.
    redirectTo: 'home',
  },
  // The other routes go here
];

Where to go from here?

As stated in the introduction, this app is a starting point and should be fairly straight-forward to enhance it to your liking.

Additional libraries

Use either ng-bootstrap or ngx-bootstrap if you want to use Angular implementations of Bootstrap components like dropdowns, tabs, collapse, etc. Both libraries are great options, pick the one you like best.

If your apps have a lot of forms, use formly for a declarative way of defining your forms, without writing any of the form templates.

Themes and colors

To tweak Bootstrap's appearance, open src/styles.scss and set the variables. Make sure to define the variables before importing Bootstrap:

$dark: hotpink;
$jumbotron-bg: #333;
$secondary: limegreen;
$body-bg: #555;
@import '~bootstrap/scss/bootstrap';

Another great option is Bootswatch which offers more than 20 different Bootstrap based layouts

Conclusion

In this tutorial, you learned how to create a basic Angular application, and use Bootstrap to create a layout with header and footer.

The app has several pages that are lazy loaded. The Login page has a form with basic validation and a redirect back to the Home page.

In case you have any questions, feel free to leave a comment on DEV or send me a message on Twitter!

Big thanks to Jeffrey and Chau for reviewing this post!

Happy coding!

Cheers, beeman 🐝

Automate your DEV Posts using GitHub Actions

beeman 🐝 — Sun, 05 Jul 2020 09:03:50 +0000

Over the last few days I've been working on getting my website online. The most important part of my site is the blog, and my idea is that I cross-post¹ my content between my website and DEV.

DEV makes this super easy as it integrates with Stackbit. Within a few clicks I was up and running with a fresh GitHub repo containing a Gatsby app connected to Netlify for building and hosting.

The build on Netlify happens in one of two occasions: when my content on DEV updates or when the GitHub repo updates.

With this setup in place I moved a lot of potential obstacles out of the way, there is very little for me to worry about. Most importantly though, I can manage a big part of my site using Git, which I love!

beeman 🐝

@beeman_nl

I moved some of my Medium posts to dev.to and I'm blown away at how great it is.

The markdown based blog by itself is awesome, but the integration with @stackbithq is the cherry on top, it allows you to generate a static site from your blog in a few clicks 🔥

14:30 PM - 04 Jul 2020

0 14

After declaring my love to this amazingly easy to use stack on Twitter, I got a reply from Maxime. He told me about a tool he created to publish your blogs from GitHub to DEV, which means my I can manage my complete site using Git, even better!

Maxime Robert

@maxime1992

@beeman_nl @stackbithq I guess you're all setup now but I built a small cli to publish on dev to which you can use locally or on CI. Setup once, then just git push your changes on github and it'll be kept in sync 😁
dev.to/maxime1992/man…

19:56 PM - 04 Jul 2020

0 1

In his post you can find the all the steps you need to set this up. The process is pretty straightforward and very well described. In the guide he explains how to use Travis CI to set up automatic publishing, but I'd rather use GitHub Actions.

In order to get started you need to finish the 2 steps of Maxim's tutorial then come back here and continue below. I'll wait.

1. Set the DEV API Token in the repo settings.

Navigate to the Settings page of the repo and select Secrets.

Click New Secret and set the name to DEV_TO_GIT_TOKEN and paste the DEV API key in the value field, then click Add Secret.

2. Create the GitHub Actions Workflow file.

Create the file .github/workflows/build.yml and add this content:

3. That's it!

After your next push, GitHub picks up the workflow and starts executing it. You can follow the process in the Actions tab.

Conclusion

Maxim's tool is an amazing addition to my publishing setup, which consists of a repo for my site and another for my content. I'll probably merge them at some point but at this moment I have bigger fish to fry.

I have created a small helper script that syncs content from DEV back my local repo, so I now have a full sync. This comes in handy after creating a new draft on DEV and allows you to make changes to the blog through their UI too.

I'm considering to wrap the syncing up in a tool that I can just run in the background while publishing, and I'd love to have a local preview of the blog that I'm writing so stay tuned for more!

Thanks!

Thanks for reading my post! In case you have any questions, feel free to leave a comment on DEV or send me a message on Twitter!

Happy coding!

Cheers, beeman 🐝

Cross-posting is considered bad for your SEO score. To address this issue, DEV conveniently supports the canonical_url property. Another reason to ❤️ DEV! ↩

Using yarn with Angular CLI

beeman 🐝 — Fri, 03 Jul 2020 05:03:28 +0000

When running ng new the Angular CLI uses npm as the default package manager. In this tutorial you will learn how you can set a different package manager so that your project gets created with the correct lock file.

This tutorial should work for Angular version 6 and higher

Configure the package manager

To enable yarn for Angular CLI you have to run the following command:

ng config -g cli.packageManager yarn

Additionally, Angular CLI has support for cnpm, a package manager that works behind the Chinese firewall. As expected, you can activate it with this command:

ng config -g cli.packageManager cnpm

If at any point you want to revert back to npm run this:

ng config -g cli.packageManager npm

Global Angular CLI config file

Because we passed in the -g flag in our ng config command, the changes are stored in the global Angular CLI configuration. If for whatever reason you like to change the package manager for the current project only, you can simply leave out the -g flag.

The global configuration file is stored in <YOUR_HOMEDIR>/.angular-config.json and in the snippet below you can see how the settings are stored.

$ cat ~/.angular-config.json
{
  "version": 1,
  "cli": {
    "packageManager": "yarn"
  }
}

Thanks!

Thanks for reading my article, I hope it was useful. Feel free to reach out and follow me on Twitter or leave a comment on DEV! 🐝