DEV Community: Marco Streng

Handling a maintenance page with Amazon CloudFront, AWS WAF and CDK

Marco Streng — Mon, 31 Mar 2025 06:36:24 +0000

Nobody really wants it, but sometimes you need it – even if it's just for a short period of time: A maintenance page.

In this blog post I want to describe how you can setup a maintenance page when working with CloudFront in AWS.

Architecture

CloudFront does not have a built-in functionality to set a web application into maintenance mode. A common way to achieve this is by integrating a Web Application Firewall (WAF) before CloudFront. With WAF and its Web ACLs (Web Access Control Lists) you can block all requests against your CloudFront domain and instead respond with a maintenance page. What at first seems like a detour actually brings with it several advantages. More on that below.

Challenge: multi-region

WAF has an important requirement if it is used together with CloudFront: WAF resources must be deployed in us-east-1. Because CloudFront is a global resource, WAF must also be global (-> technically that means us-east-1). This has to be considered if your web application runs in another region. In the following code example we assume such a case.

Code example

CDK

The example application consists of two stacks: A SecurityStack including our WAF and Web ACLs which will be deployed in us-east-1 and an AppStack which will be deployed in the default region (e.g. eu-central-1).

const app = new cdk.App();

new SecurityStack(app, "SecurityStack");
new AppStack(app, "AppStack");

SecurityStack

The SecurityStack uses an environment variable MAINTENANCE_MODE to control whether requests should be blocked or not.

As mentioned above, our example assumes that the application runs in a different region than us-east-1. As it is not possible to share CloudFormation Exports between regions, we have to write the ARN of the created WAF to the AWS Systems Manager Parameter Store. This allows us to retrieve the ARN via an API call inside the AppStack and configure CloudFront to use the WAF (see: AppStack).

export class SecurityStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, {
      ...props,
      env: {
        region: "us-east-1",
      },
    });

    const { MAINTENANCE_MODE } = process.env;

    const maintenancePageHtmlContent = readFileSync(
      resolve(__dirname, "html", "maintenance.html"),
      "utf8"
    );

    const webACL = new aws_wafv2.CfnWebACL(this, "WebACL", {
      scope: "CLOUDFRONT",
      defaultAction: {
        ...(MAINTENANCE_MODE === "true"
          ? {
              block: {
                customResponse: {
                  responseCode: 200,
                  customResponseBodyKey: "maintenance",
                },
              },
            }
          : {
              allow: {},
            }),
      },
      customResponseBodies: {
        maintenance: {
          content: maintenancePageHtmlContent,
          contentType: "TEXT_HTML",
        },
      },
    });

    // Write ARN of Web ACL into ParameterStore to make it available for Stacks in other regions
    new cdk.aws_ssm.StringParameter(this, "WebACLParameter", {
      parameterName: "/yourApplicationName/webACLArn",
      stringValue: webACL.attrArn,
    });
  }
}

AppStack

To retrieve the ARN of the WAF we can use an Custom Resource and perform an API call against the Parameter Store (SSM).

export class AppStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // Fetch ARN for webACL from ParameterStore in us-east-1
    const webACLArnParameter = new custom_resources.AwsCustomResource(
      this,
      "WebACLArnParameter",
      {
        onUpdate: {
          service: "SSM",
          action: "GetParameter",
          parameters: {
            Name: "/yourApplicationName/webACLArn",
          },
          region: "us-east-1",
          physicalResourceId: custom_resources.PhysicalResourceId.of(
            Date.now().toString()
          ),
        },
        policy: custom_resources.AwsCustomResourcePolicy.fromSdkCalls({
          resources: custom_resources.AwsCustomResourcePolicy.ANY_RESOURCE,
        }),
      }
    );

    // Create CloudFront Distribution
    new aws_cloudfront.Distribution(this, "Distribution", {
      webAclId: webACLArnParameter.getResponseField("Parameter.Value"),
    });
  }
}

Advantages

Amazon's Web Application Firewall (WAF) is a very flexible service which brings a lot more functionality than used above.

Developer access during maintenance

When your application is in maintenance mode it might be useful to grant access for example to you as a developer (team). Therefore we can configure additional rules in our Web ACL. On top of the default action which blocks all access an additional rule can grant access for specific IP addresses (See: Docs)

Security layer

If WAF and Web ACL is already deployed, we can also increase security by adding AWS managed rules. AWS provides a variety of managed rules to protect e.g. against DDOS attacks etc. (See: Docs)

Full example

You can find the full code example on GitHub

Suggestions or feedback

If you have any kind of feedback, suggestions or ideas - feel free and write a comment below this article. There is always space for improvement!

Dealing with CDK Custom Resources and failures

Marco Streng — Fri, 28 Feb 2025 12:26:51 +0000

With the AwsCustomResource Constrcut CDK provides an easy way to execute AWS SDK calls during CloudFormation deployments. Common use cases are e.g. fetching values from Parameter Store or executing Lambda Functions.

How does it work?

To perform SDK calls CloudFormation deploys a singleton Lambda Function including the JavaScript SDK. This function will be executed during CloudFormation life cycle events (CREATE, UPDATE and DELETE) and perform the SDK calls against the AWS APIs. The response JSON of the singleton Lambda is stored in S3 and will be read from CloudFormation.

What about failures?

As mentioned in the title this post is about failures. Because at this point I was a little irritated when executing Lambda Functions this way.

Let's say we have a Lambda Function called "MigrationLambda" to do some database operation (e.g. data migrations) during our deployment. Therefore we can use AwsCustomResource to execute our MigrationLambda on every UPDATE event of our CloudFormation Stack.

new custom_resources.AwsCustomResource(this, 'CustomResource', {
  onUpdate: {
    service: 'Lambda',
    action: 'invoke',
    parameters: {
      FunctionName: migrationLambda,
      InvocationType: 'Event',
      Payload: JSON.stringify({
        someKey: 'someValue'
      }),
    },
  },
});

So far - so good.
But what happens if the MigrationLambda fails for some reason… ? Nothing. Our CloudFormation deployment will be successful.

Ok, but why?

As mentioned in the beginning the singleton Lambda Function is responsible for the AWS SDK calls. In other words it is just a "carrier" between CloudFormation and the AWS APIs.

That means for the state of the CustomResource (SUCCESS or FAILED) it is only relevant if the API call itself was successful or not. So if for example the MigrationLambda would not exits any more and the API call returns an error our whole deployment would fail.

Solution

But what if we want the deployment to fail? In our example we want to notice if the database migration was not successful.

You can achieve this by using a custom Provider instead auf the singleton Lambda Function which comes out of the box.

Provider Framework vs. Lambda directly

There are two ways to use a Lambda Function as custom Provider. You can use the Provider Framework or a Lambda directly. I also was a bit confused at this point at the beginning, because the way you handle the response depends on the variant you choose.

The main difference here is that the Provider Framework takes care about sending your response to the S3 Bucket. In other words you simply can return data or throw an error in your Lambda Function. When using a Lambda Function directly you have to perform a PUT request against the pre-sigend S3 URL by yourself. AWS recommends using the Provider Framework ("[...] unless you have good reasons not to.")!

Anyway, with both variants we have full control of what happens with our deployment depending on the custom resource Lambda.

// CDK

const providerLambda = new aws_lambda_nodejs.NodejsFunction(
  this,
  "ProviderLambda",
  {
    entry: path.join(__dirname, "index.ts"),
  }
);

const provider = new custom_resources.Provider(this, "Provider", {
  onEventHandler: providerLambda,
});

new CustomResource(this, "CustomResource", {
  // Using the Provider Framework
  serviceToken: provider.serviceToken,

  // Alternative: Using Lambda directly
  // serviceToken. providerLambda.functionArn,

  properties: {
    timestamp: new Date().toISOString(),
  },
});

Lambda Function

export const handler = async (
  event: AWSLambda.CloudFormationCustomResourceEvent,
  _context: AWSLambda.Context
) => {
  // your business logic here ...

  // Variant 1: Using the Provider Framework
  // Success case
  const responseObject: AWSLambda.CloudFormationCustomResourceResponse = {
    Status: "SUCCESS",
    PhysicalResourceId: "SomeCustomResourceId",
    StackId: event.StackId,
    RequestId: event.RequestId,
    LogicalResourceId: event.LogicalResourceId,
    Data: {
      key: "some custom value",
    },
  };
  return responseObject;

  // Error case
  throw new Error("Your error message");



  // Varinat 2: Using Lambda directly
  // Success case
  const responseObject: AWSLambda.CloudFormationCustomResourceResponse = {
    Status: "SUCCESS",
    PhysicalResourceId: "SomeCustomResourceId",
    StackId: event.StackId,
    RequestId: event.RequestId,
    LogicalResourceId: event.LogicalResourceId,
    Data: {
      key: "some custom value",
    },
  };
  await fetch(event.ResponseURL, {
    body: JSON.stringify(responseObject),
    method: "PUT",
  });

  // Error case
  const responseObject: AWSLambda.CloudFormationCustomResourceResponse = {
    Status: "FAILED",
    Reason: "Your error message",
    PhysicalResourceId: "SomeCustomResourceId",
    StackId: event.StackId,
    RequestId: event.RequestId,
    LogicalResourceId: event.LogicalResourceId,
  };
  await fetch(event.ResponseURL, {
    body: JSON.stringify(responseObject),
    method: "PUT",
  });
};

Points to consider

UPDATE event

By default the CustomResource will no be executed when updating the CloudFormation stack, even if the code of the Provider changes. This only happens if properties change between deployments. Therefore we can set a timestamp to achieve the required behaviour (see CDK example above).

Life cycle events in generell

Our Provider will be executed on every life cycle event. So we have to take care which events are relevant inside our Lambda code. Maybe you only want it to do something on CREATE but nut on UPDATE and DELETE etc.

Suggestions or feedback

If you got any kind of feedback, suggestions or ideas - feel free and write a comment below this article. There is always space for improvement!

Simple ChatApp with AWS AppSync Events, CDK & React

Marco Streng — Sat, 15 Feb 2025 07:21:05 +0000

A view days ago AWS released the L2 CDK construct for the new AppSync Events API.

With this serverless WebSocket API we can build a simple chat application with just a few lines of code.

Infrastructure

Our architecture diagram is not extensive. We use the mentioned AppSync Events API, an S3 Bucket for storing our React application and CloudFront as CDN.

CDK

AppSync Events API

We create an AppSync Events API with the new EventsApi construct. For simplicity we keep all the defaults, including API Key as auth provider. In a, lets say, more real-world use case, you probably would choose Cognito which is also supported by AppsSync Events out of the box.

We also create a namespace for our chat application: chat. Channel namespaces provide a scalable way to structure our API. Later in this article we will use this feature to handle multiple chatrooms, like e.g. chat/gardening.

// Events Api
const eventsApi = new appsync.EventApi(this, "EventsApi", {
  apiName: "EventsChat",
});

// Channel
eventsApi.addChannelNamespace("chat");

S3 & CloudFront

For our user interface which will be implemented as a React application we create a S3 Bucket and a CloudFront distribution.

// S3
const clientBucket = new Bucket(this, "ClientBucket", {
  accessControl: BucketAccessControl.PRIVATE,
});
new BucketDeployment(this, "ClientDeployment", {
  destinationBucket: clientBucket,
  sources: [
    Source.asset(path.resolve(__dirname, "[path-to-your-client]")),
  ],
});

// CloudFront
new aws_cloudfront.Distribution(this, "Distribution", {
  defaultRootObject: "index.html",
  errorResponses: [
    {
      httpStatus: 403,
      responseHttpStatus: 200,
      responsePagePath: "/index.html",
    },
    {
      httpStatus: 404,
      responseHttpStatus: 200,
      responsePagePath: "/index.html",
    },
  ],
  defaultBehavior: {
    origin:
      aws_cloudfront_origins.S3BucketOrigin.withOriginAccessControl(
        clientBucket
      ),
  },
});

UI

I recommend setting up a fresh React application with Vite. Additionally I use tailwindcss to implement the UI.

In the following steps I just show the relevant parts. Of course there is some more code for rendering and handling stuff like e.g. focus. See the full example on GitHub.

We use the Amplify library which provides a very easy way to interact with the Events API. The following code is quite close to the official documentation.

Data structure

The data model for the events we will subscribe to consists of id, type and event which stands for the payload.

For this example our payload includes the text of the chat message and information about the author of it.

type Event = {
  id: string;
  type: string;
  event: {
    text: string;
    author: {
      id: string;
      name: string;
    };
  };
};

Subscription

As I already mentioned we can support dynamic chat rooms via channel namespaces. Therefore we simply use the URL pathname. So for the mentioned "gardening" example that could be something like https://www.my-chat-app.com/gardening.

With the following code we can subscribe for messages in our chat room and store those in a React state.

const chatRoom = window.location.pathname;

const [messages, setMessages] = useState<Event[]>([]);

useEffect(() => {
    let channel: EventsChannel;

    const connectAndSubscribe = async () => {
      channel = await events.connect(`chat${chatRoom}`);
      channel.subscribe({
        next: (data: Event) => {
          setMessages((prev) => [...prev, data]);
        },
        error: (err) => console.error("error", err),
      });
    };

    connectAndSubscribe();

    return () => channel && channel.close();
  }, [chatRoom]);

Publishing

Also publishing chat messages is very easy with Amplify.

async function publishMessage(text: string) {
  await events.post(`chat${chatRoom}`, {
    text,
    author: {
      name: user.name,
      id: user.id,
    },
  });
}

Persistence

A note regarding persistence. For now our chat application does not include any persistence layer. That means all chat message just live in the users browser and are gone after closing it. Of course there are multiple ways to add this feature with AWS Services. Since this post is about AppSync Events (in other words: WebSockets 🙂), I won't go into this in depth.

Conclusion

Its great to see what can be achieved just by using those powerful AWS Services, the official code examples and some time playing around with tailwindcss 😁

Full example

You can find the full code example on GitHub.

Suggestions or feedback

If you got any kind of feedback, suggestions or ideas - feel free and write a comment below this article. There is always space for improvement!

AWS AppSync Subscriptions with DynamoDB Streams, Lambda and Serverless

Marco Streng — Fri, 11 Jun 2021 12:22:07 +0000

With AWS AppSync a GraphQL Subscription always has to be triggered by a GraphQL Mutation. But there are use cases in which you would like to trigger Subscriptions from another kind of event, for example an update in your DynamoDB which was done by an external service. In this article I'd like to show you how you can do this with DynamoDB Streams, Lambda and the Serverless framework.

Example

To keep this example simple let's say we develop a game with a list of user. Each user has got a name and a current score value. If the score of a user changes in our DynamoDB, we want to publish this new score to all subscribers.

Architecture

When a user item in our DynamoDB gets updated we execute a Lambda function via DynamoDB Streams. This Lambda function will execute the GraphQL Mutation on which our clients can subscribe to. As the updated data is already stored in our DynamoDB, the Mutation does not need a data source. It should only pass the incoming data to the subscribers.

Schema

First off all we create our Schema. The Mutation which will be executed by the Lambda is called updateUserScore and takes the id and the new score of the user as arguments. It returns both fields within the UpdatedUserScore type.

The Subscription is called onUpdateUserScore. With the AppSync annotation @aws_subscribe() we can easily subscribe to multiple Mutations. The optional id parameter allows to subscribe to all user or to a specific one.

type User {
  id: ID!
  name: String!
  score: Int
}

type Query {
  listUser: [User]
}

type UpdatedUserScore {
  id: ID!
  score: Int!
}

type Mutation {
  createUser(name: String!): User!
  updateUserScore(id: ID!, score: Int!): UpdatedUserScore!
}

type Subscription {
  onUpdateUserScore(id: ID): UpdatedUserScore
    @aws_subscribe(mutations: ["updateUserScore"])
}

schema {
  query: Query
  mutation: Mutation
  subscription: Subscription
}

Infrastrucutre

With the serverless-appsync-plugin it's easy to set up our AppSync instance. To keep the example simple we use AWS_IAM for authentication. In real world you probably would use AMAZON_COGNITO_USER_POOLS in addition so that your client app can also authenticate against AppSync.

As mentioned before, the Mutation does not need a data source. Therefore we can create a data source with type NONE.

Don't forget the role statement so that our Lambda function is allowed to execute the AppSync Mutation.

service: subscription-demo

plugins:
  - serverless-appsync-plugin

provider:
  name: aws
  runtime: nodejs12.x
  region: eu-central-1
  iamRoleStatements:
    - Effect: Allow
      Action:
        - dynamodb:Scan
        - dynamodb:Query
        - dynamodb:PutItem
      Resource:
        - !GetAtt DynamoDbTableUser.Arn
        - !Join [ '', [ !GetAtt DynamoDbTableUser.Arn, '/*' ] ]
    - Effect: Allow
      Action:
        - appsync:GraphQL
      Resource:
        - !GetAtt GraphQlApi.Arn
        - !Join [ '/', [ !GetAtt GraphQlApi.Arn, 'types', 'Mutation', 'fields', 'updateUserScore' ] ]

custom:
  appSync:
    name: ${self:service}
    authenticationType: AWS_IAM
    mappingTemplates:
      - dataSource: TableUserDS
        type: Query
        field: listUser
      - dataSource: None
        type: Mutation
        field: updateUserScore
      - dataSource: TableUserDS
        type: Mutation
        field: createUser
    dataSources:
      - type: NONE
        name: None
      - type: AMAZON_DYNAMODB
        name: TableUserDS
        description: 'DynamoDB DynamoDbTableUser table'
        config:
          tableName: !Ref DynamoDbTableUser

functions:
  handleDynamoDbStream:
    handler: backend/handleDynamoDbStream.handler
    environment:
      APP_SYNC_API_URL: !GetAtt GraphQlApi.GraphQLUrl
    events:
      - stream:
          type: dynamodb
          arn: !GetAtt DynamoDbTableUser.StreamArn

resources:
  Resources:
    DynamoDbTableUser:
      Type: AWS::DynamoDB::Table
      Properties:
        AttributeDefinitions:
          - AttributeName: id
            AttributeType: S
        KeySchema:
          - AttributeName: id
            KeyType: HASH
        BillingMode: PAY_PER_REQUEST
        StreamSpecification:
          StreamViewType: NEW_IMAGE

Mapping-Template

The request and response template for our Mutation are quite simple:

## Mutation.updateUserScore.request.vtl

{
    "version": "2017-02-28",
    "payload": $util.toJson($context.arguments)
}

## Mutation.updateUserScore.response.vtl

$util.toJson($ctx.result)

Lambda function

Inside our Lambda function we create an AppSyncClient and the Mutation. DynamoDB Streams are batched. Therefore wie have to iterate over the incoming Records and execute the Mutation.

const AWS = require('aws-sdk')
const appsync = require('aws-appsync')
const gql = require('graphql-tag')
const fetch = require('node-fetch')

if (!globalThis.fetch) globalThis.fetch = fetch

const graphqlClient = new appsync.AWSAppSyncClient({
  url: process.env.APP_SYNC_API_URL,
  region: process.env.AWS_REGION,
  auth: {
    type: 'AWS_IAM',
    credentials: {
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
      sessionToken: process.env.AWS_SESSION_TOKEN
    }
  },
  disableOffline: true
})

const mutation = gql`mutation UpdateUserScore($id: ID!, $score: Int!) {
  updateUserScore(id: $id, score: $score) {
    id
    score
  }
}`

exports.handler = (event) => {
  event.Records.forEach((record) => {
    if (record.eventName !== 'MODIFY') return

    const item = AWS.DynamoDB.Converter.unmarshall(record.dynamodb.NewImage)

    graphqlClient.mutate({
      mutation,
      variables: {
        id: item.id,
        score: item.score
      }
    })
  })
}

Result

Suggestions or feedback

If you got any kind of feedback, suggestions or ideas - feel free and write a comment below this article. There is always space for improvement!

Static site builds with GitHub Actions and GraphCMS

Marco Streng — Wed, 05 Aug 2020 13:02:43 +0000

In this blog post I'd like to show you how to trigger a GitHub Actions Workflow from GraphCMS to deploy your static site with the latest content.

As GitHub requires a specific payload we need to set a small function between GraphCMS and GitHub.

This example uses AWS Lambda for the serverless function and Amazon S3 for storage. Of course you can use the cloud provider of your choice.

Overview - What we need to do

GitHub Actions workflow
GitHub access token
Lambda function
GraphCMS webhook
Test it!

1. GitHub Workflow

Our workflow should build the static recourses and deploy them. We use Gatsby as static site generator. So our workflow should be straightforward. The only special one is the trigger workflow_dispatch. More about this later.

name: Deploy on GraphCMS Publish Event

on: [workflow_dispatch]

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Use Node.js
        uses: actions/setup-node@v1
        with:
          node-version: '12.x'
      - run: yarn install
      - run: yarn lint
      - run: yarn test
      - run: yarn build
      - uses: actions/upload-artifact@v2
        with:
          name: public
          path: public/
 deploy:
    name: Deployment
    runs-on: ubuntu-latest
    needs: [build]
    steps:
      - uses: actions/checkout@v2
      - name: Use Node.js
        uses: actions/setup-node@v1
        with:
          node-version: '12.x'
      - uses: actions/download-artifact@v2
        with:
          name: public
          path: public/
      - run: yarn install
      - run: yarn serverless:deploy

2. GitHub Access Token

To trigger our workflow from 'outside' we need to create a personal access token on GitHub.

Login to GitHub and goto https://github.com/settings/tokens. Create a new token and save it anywhere secure, we will need it later.

3. Lambda function

Our Lambda function will be called by the GraphCMS webhook. The function then will call the GitHub API and trigger our GitHub workflow.
We will call the worklow_dispatch endpoint which we use as trigger in our GitHub workflow in step 1. (GitHub Docs)

const axios = require('axios')

exports.handler = async (event) => {
  const { status } = await axios.post(
    'https://api.github.com/repos/[OWNER]/[REPO]/actions/workflows/[WORKFLOW-FILENAME]/dispatches',
    { ref: 'master' },
    {
      headers: {
        Accept: 'application/vnd.github.v3+json',
        Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
      }
    }
  )

  if (status === 204) {
    return {
      statusCode: 200,
      body: 'GitHub API called'
    }
  }

  return {
    statusCode: 400
  }
}

You will have to change [OWNER], [REPO] and [WORKFLOW-FILENAME] with your data. The GitHub token we created in step 2 is stored as an environment variable (process.env.GITHUB_TOKEN).

Parameter ref in the request body is required by GitHub. You can specify your branch name here.

4. GraphCMS webhook

Login to GraphCMS and create a new webhook. Paste the Lambda endpoint into the Url field. GraphCMS allows you to choose Content Model, Stage and Action to control when our webhook is triggered.

(Of course you should care about security and also work with an Authorization Header here)

5. Test it!

Depending on which triggers you configured in the GraphCMS webhook settings (mostly publish and unpublish) you now can trigger a build and see your workflow running on GitHub.

Introduction: styled-off-canvas

Marco Streng — Thu, 28 May 2020 10:49:14 +0000

As a big fan of styled-components, I always had the need for an Off-Canvas or Burger-Menu in my projects.

When working with styled-components, it feels unpleasant to use one of the plain CSS based menus. You have to import .css files, you probably have to overwrite some styling, your styling is divided in 'two worlds': plain CSS and styled-components. So I wrote styled-off-canvas.

Demo

Yes, there is a DEMO

Components

styled-off-canvas comes with three components: <StyledOffCanvas />,<Menu /> and <Overlay />.

<StyledOffCanvas /> is a wrapping component which provides all settings/properties.

<Menu /> is the off-canvas menu itself. You can pass anything you want as children (e.g. styled list of react-router links)

<Overlay /> is an optional component which renders a semi-transparent layer above your app content.

Implementation

This is a simple example of how to use styled-off-canvas. You can also find a code example here.

import React, { useState } from 'react'
import { StyledOffCanvas, Menu, Overlay } from 'styled-off-canvas'

const App = () => {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <StyledOffCanvas
      isOpen={isOpen}
      onClose={() => setIsOpen(false)}
    >

      <button onClick={() => setIsOpen(!isOpen)}>Toggle menu</button>

      <Menu>
        <ul>
          <li>
            <a onClick={() => setIsOpen(false)}>close</a>
          </li>
          <li>
            <a href='/about'>About</a>
          </li>
          <li>
            <a href='/contact'>Contact</a>
          </li>
        </ul>
      </Menu>

      <Overlay />

      <div>this is some nice content!</div>
    </StyledOffCanvas>
  )
}

export default App

Customization

There are a lot of properties to customize the menu, like for example: colors, position, size or transition-duration.
Additionally you can use the styled-components css property on every component.

Plans for the future

styled-off-canvas should stay lightweight and simple. So I don't want hundrets of options and possibilities. Currently I'm thinking about adding some transition to the page content.

Suggestions or feedback

If you got any kind of feedback, suggestions or ideas - feel free! Write a comment below this article or fork/clone from GitHub. There is always space for improvement!

How to (really) remove eventListeners in React

Marco Streng — Fri, 27 Mar 2020 06:38:40 +0000

Sometimes you need to track user interaction like e.g. scrolling or events like the change of the window size. In this cases you will add an eventListener to your window/document/body or whatever.

When working with eventListeners you always have to take care about cleaning them up, if the component doesn't need them anymore or gets unmounted.

Mount & Unmount

A common and simple use case is to add a listener after the initial mount and remove it when the component unmounts. This can be done with the useEffect hook.

Example:

  const onKeyDown = (event) => { console.log(event) }

  useEffect(() => {
    window.addEventListener('keydown', onKeyDown)

    return () => { window.removeEventListener('keydown', onKeyDown) }
  }, [])

❗️Don't forget the second parameter [] when calling useEffect. Otherwise it will run on every render.

State change or property change

What work's perfect in the example above, won't work when you add and remove listeners depending on a state or prop change (as i had to learn).

Example:

  // ⚠️ This will not work!
  const [isVisible, setVisibility] = useState(false)

  const onKeyDown = (event) => { console.log(event) }

  handleToggle((isVisible) => {
    if (isVisible) window.addEventListener('keydown', onKeyDown)
    else window.removeEventListener('keydown', onKeyDown)
  })

  return (
    <button onClick={() => setVisibility(!isVisible)}>Click me!</button>
  )

After clicking the button the second time the eventListner should be removed. But that's not what will happen.

But why?

The removeEventListener(event, callback) function will internally do an equality check between the given callback and the callback which was passed to addEventListener(). If this check doesn't return true no listener will be removed from the window.

But we pass in the exact same function to addEventListener() and removeEventListener()! 🤯

Well,... not really.
As React renders the component new on every state change, it also assigns the function onKeyDown() new within each render. And that's why the equality check won't succeed.

Solution

React provides a nice Hook called useCallback(). This allows us to memoize a function and the equality check will succeed.

Example

  const [isVisible, setVisibility] = useState(false)

  const onKeyDown = useCallback((event) => { console.log(event) }, [])

  handleToggle((isVisible) => {
    if (isVisible) window.addEventListener('keydown', onKeyDown)
    else window.removeEventListener('keydown', onKeyDown)
  })

  return (
    <button onClick={() => setVisibility(!isVisible)}>Click me!</button>
  )

❗️Again: Don't forget the second parameter [] when calling useCallback(). You can pass in an Array of dependencies here, to control when the callback should change. But that's not what we need in our case.

—

If you got any kind of feedback, suggestions or ideas - feel free to comment this blog post!

Handle 'componentWillReceiveProps' deprecation warning

Marco Streng — Tue, 10 Mar 2020 07:38:50 +0000

As part of the implementation of async rendering in React, there are a few lifecycle methods which will be deprecated in React 17 (see React Blog). A common used one is componentWillReceiveProps. In most cases it is used to handle the
props change of a component.

So what to do?

One solution is to use the static getDerivedStateFromProps method. There is a great 'HowTo' dev.to Post from Larry Price.

Another solution is to use React Hooks, especially the useEffect() Hook. This might be a nice solution if you have a small component and want to switch to a functional component within this change.

Here is a simple example. Imagine we are rendering a table component with a list of items. All items must initially run through the doSomething() method.

previous code

doSomething (items) {
  // some code to sort items ...
  return items
}

state = {
  items: this.props.items
}

componentWillReceiveProps (nextProps) {
  this.setState({
    items: doSomething(nextProps.items)
  })
}

with Hooks

const doSomething = (items) => {
  // some code to sort items ...
  return items
}

const [items, setItems] = useState(doSomething(props.items))

useEffect(() => {
  setItems(defaultSorting(items))
}, [items])

We can use the useEffect() Hook which by default runs on every render. To avoid unnecessary calls, we use [items] as the second parameter. So useEffect() only runs when the property items has changed.

Important notice

Before switching to getDerivedStateFromProps() or useEffect() you should check if you really need this property handling. Have a look at this official React Blogpost for common bugs and anti-pattern.

Sometimes we write some properties to the state even if we don't need to. If you for example need to sort a list which comes from a property, do it during the render and avoid writing it in the component state.

—

If you got any kind of feedback, suggestions or ideas - feel free to comment this blogpost!

Introduction: react-boilerplate

Marco Streng — Sun, 01 Dec 2019 10:15:59 +0000

Why

First of all: I'm a fan of create-react-app. It's a fantastic tool, especially if you use it the way it's intended.

In my case I like to work with styled component and Standard. This is of course also possible with CRA via detours (e.g. react-app-rewired), but CRA loses something of its advantage and concept.

Besides the technologies and tools I like to work with, it's important to me to understand what happens under the hood. I want to know how webpack works, learn, try things out and be flexible.

And I also want something from which I can start a new project super fast — a react-boilerplate.

Motivation & Goals

keep it simple and lightweight
understand how things work
be flexible
be able to start new projects fast
keep it maintainable
Learn, learn, and learn

Scope

When building a boilerplate there is always one question:
What should be the scope of it?
In case of a react-boilerplate, this question for example ends up in thoughts about adding a global state management or not.

As I mentioned before, my goal was to keep it simple and lightweight. So for example I decided against adding global state management (like Redux). Sometimes you build just small project which don't need a global state. And even if you need it, the simplicity and power of the React Context API is often a good solution and implemented quickly.

I was also thinking about adding cypress.io because I like this testing framework so much and it's so super easy to use. But to be realistic, we implement these tests very late in a project.

To put it in a nutshell: Add tools and frameworks only when you really need them.

Frameworks & Tools

Usage

The easiest way to use this boilerplate is the built-in template function from GitHub. This can be done by simply clicking on the green "Use this template" Button on the repository page.

Alternative way:

$ mkdir boilerplate && cd boilerplate
$ curl -fsSL https://github.com/marco-streng/react-boilerplate/archive/master.tar.gz | tar -xz --strip-components 1

Suggestions or feedback

If you got any kind of feedback, suggestions or ideas - feel free! Write a comment below this article or fork/clone from GitHub. There is always space for improvement!

How to add data-* attributes to your component library and benefit from them in your E2E tests

Marco Streng — Thu, 19 Sep 2019 11:13:43 +0000

Intro

When building a component library, one of the most important things is a seamless and clean documentation of the available properties of a component.

Users of your component library should not be able to write random properties on components which are not used by it. Otherwise an error like Warning: React does not recognize the 'isVisible' prop on a DOM element. [...] If you accidentally passed it from a parent component, remove it from the DOM element. can be thrown quickly.

The data-* and why we sometimes need it

There are use cases in which users need to have the ability to pass some kind of random properties on the components.

For me, such a use case was adding selector attributes for End-2-End tests like data-test-element="header" to the libraries components in my project.
(BTW: I love to write my E2E tests with cypress.)

Solution

A small and simple function which takes your property object and returns just valid properties that should appear in the rendered markup.

const validateProps = (props) => {
  const newProps = {}

  Object.keys(props).forEach((key) => {
    if (key.startsWith('data-') || key === 'className') newProps[key] = props[key]
  })

  return newProps
}

Usage

In your components you can extract the properties which are used by it self. All other properties are passed through validateProps().

const Badge = ({ onToggle, isActive, children, ...props }) => (
  <Wrapper
    isActive={isActive}
    onClick={onToggle}
    {...validateProps(props)}
  >
    {children}
  </Wrapper>
)

??? className ???

Maybe you wonder why validateProps() keeps the className property? That's because I work with styled-components. If you add some custom styling from outside to a component you will have to write this property on the component (see styled-component docs)

Prod vs. Dev

Depending on how and where you run your tests, you maybe don't want to see those data-test-* attributes in your markup in production.

In this case I recommend babel-plugin-react-remove-properties.

Usage

Filter all data-test-element properties only in production with the following config in the .babelrc of your project.

{
  "env": {
    "production": {
      "plugins": [
        [
          "react-remove-properties", {
            "properties": [
              "data-test-element"
            ]
          }
        ]
      ]
    },
  }
}