Forem: Layton Whiteley

Using vanilla-extract in an nx workspace (webpack)

Layton Whiteley — Sun, 23 Oct 2022 16:03:12 +0000

Overview

Recently, I have been curious about zero-runtime css-in-js libraries and the performance benefits they bring. One such library, relatively new, is vanilla-extract. Because I like to build projects with nx, I was curious if there is already support for it but currently there isn't as yet.

This aims to show a quick and easy way to add support for vanilla-extract in a react/webpack app in an nx workspace.

What is vanilla-extract?

vanilla-extract is all about zero-runtime style sheets in TypeScript (or JavaScript). If you’ve used Sass or Less in the past, you already know how powerful they can be for things like theming, organization, and preprocessing of your app’s styles.

Setup

Let's create a workspace

Please see below the command to create the nx workspace and the options taken to follow along.

Note: the current version of nx at this time is 15.0.1

npx create-nx-workspace@latest

# Choose your style: Integrated
# What to create in the new workspace: react
# Repository name: vanilla
# Application name: example-web
# Default stylesheet format: CSS
# Enable distributed caching to make your CI faster: No

Install dependencies

npm i @vanilla-extract/css
npm i --save-dev @vanilla-extract/webpack-plugin

Create custom webpack config

In order to add support, we need to do a few things:

Create a file: apps/example-web/webpack.config.js
Add rules for the css generated by vanilla-extract
Prepend these rules in the rules array already provided by nx
Replace the rules array

// file: apps/example-web/webpack.config.js
const { VanillaExtractPlugin } = require('@vanilla-extract/webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = (config) => {
  const cssRule = config.module.rules.find((rule) =>
    rule.test.toString().includes('css')
  );

  const rulesWithoutCss = config.module.rules.filter(
    (rule) => !rule.test.toString().includes('css')
  );

  const rules = [
    ...rulesWithoutCss,
    {
      ...cssRule,
      oneOf: [
        {
          test: /\.vanilla\.css$/i, // Targets only CSS files generated by vanilla-extract
          use: [
            MiniCssExtractPlugin.loader,
            {
              loader: require.resolve('css-loader'),
              options: {
                url: false, // Required as image imports should be handled via JS/TS import statements
              },
            },
          ],
        },
        ...cssRule.oneOf,
      ],
    },
  ];

  return {
    ...config,
    plugins: [...config.plugins, new VanillaExtractPlugin()],
    module: {
      ...config.module,
      rules,
    },
  };
};

Use the custom webpack config

In the file apps/example-web/project.json,
find the property webpackConfig and replace it with

"webpackConfig": "apps/example-web/webpack.config.js",

Create and use your styles

Create file apps/example-web/src/app/app.css.ts

import { style } from '@vanilla-extract/css';

export const container = style({
  padding: 10,
  background: 'blue',
});

Modify file: apps/example-web/src/app/app.tsx

import { container } from './app.css';
import NxWelcome from './nx-welcome';

export function App() {
  return (
    <div className={container}>
      <NxWelcome title="example-web" />
      <div />
    </div>
  );
}

export default App;

Run the application

npm run start example-web

Thats it!

You will now see that the page's background is blue. Not the prettiest thing but just to prove it works.
Upon inspecting the network, you can locate the css file vendor.css (at this time and for this example) which has the generated styles

Your next steps

Try it out
make your own customisations like changing the exported css file name, etc.
Leave feedback; I'd love to see how this can be improved.

see sample repository for completed solution

https://github.com/lwhiteley/nx-vanilla-extract-setup

Feature request for nx: https://github.com/nrwl/nx/issues/12771

React and Puppeteer: Pdf generation (client download and print)

Layton Whiteley — Sun, 02 Oct 2022 13:43:22 +0000

Summary

Now that the server is setup. We will now tie everything together with a client that can use this api

Setup UI

Step 1

Let's create some hooks to manage printing and downloding the generated pdf.

The following hook is responsible for:

Generating the pdf server-side
Generating a blob url for further use

How can the blob url be used after?

Printing the PDF
Downloading the PDF
View the PDF in a client (likely via an iframe)

// file: apps/ui-app/src/app/hooks/use-generate-pdf-blob-url.ts

import { useEffect, useState } from 'react';
import { useDebouncedCallback } from 'use-debounce';
import axios, { AxiosResponse } from 'axios';
import { PDFDocumentData } from '@pdf-generation/constants';
import { PdfDocProps } from '@pdf-generation/pdf-doc';
import { pdfData } from '../app.constants';

const generatePdfDocument = (data: PDFDocumentData<PdfDocProps>) => {
  return axios.post<
    PDFDocumentData<PdfDocProps>,
    AxiosResponse<{ data: number[] }>
  >('/api/pdf/generate', data);
};

export const useGeneratePDFBlobURL = ({ enabled = true } = {}) => {
  const [isGeneratingPdf, setIsGeneratingPdf] = useState(false);
  const [pdfBlobURL, setPdfBlobURL] = useState<string>();
  const [error, setError] = useState();

  const generatePdf = useDebouncedCallback(
    (data) => {
      generatePdfDocument(data)
        .then(({ data: pdfBufferData }) => {
          const blob = new Blob([new Uint8Array(pdfBufferData.data)], {
            type: 'application/pdf',
          });
          const blobURL = URL.createObjectURL(blob);

          setIsGeneratingPdf(false);
          setPdfBlobURL(blobURL);
        })
        .catch((generationError) => {
          setIsGeneratingPdf(false);
          setError(generationError);
        });
    },
    500,
    { maxWait: 2000 }
  );

  useEffect(() => {
    if (!pdfBlobURL && enabled) {
      generatePdf.cancel();
      setIsGeneratingPdf(true);
      generatePdf(pdfData);
    }

    return () => {
      if (pdfBlobURL) {
        URL.revokeObjectURL(pdfBlobURL);
      }
    };
  }, [generatePdf, pdfBlobURL, enabled]);

  return {
    isGeneratingPdf,
    pdfBlobURL,
    error,
  };
};

This next hook can be used to accept the blob url and used as an action to download the PDF

// file: apps/ui-app/src/app/hooks/use-pdf-link-downloader.ts

import { useCallback } from 'react';

export const usePDFLinkDownloader = () => {
  const downloadPdf = useCallback((blobURL: string, fileName: string) => {
    const link = document.createElement('a');
    document.body.appendChild(link);
    link.setAttribute('style', 'display: none');
    link.href = blobURL;
    link.download = fileName;

    link.click();

    setTimeout(() => {
      document.body.removeChild(link);
    }, 300);
  }, []);

  return {
    downloadPdf,
  };
};

This next hook can be used to accept the blob url and used as an action to print the PDF

// file: apps/ui-app/src/app/hooks/use-print-pdf.ts

import { useCallback } from 'react';

export const usePrintPDF = () => {
  const printPdf = useCallback((blobURL: string) => {
    const iframe = document.createElement('iframe');
    document.body.appendChild(iframe);
    iframe.style.display = 'none';
    iframe.src = blobURL;
    iframe.onload = function print() {
      setTimeout(() => {
        iframe.focus();
        iframe?.contentWindow?.print();
      }, 1);
    };
  }, []);

  return {
    printPdf,
  };
};

Thats it!

Now you can formulate the UI however you want to

To view the full solution view the repository

git clone https://github.com/lwhiteley/pdf-generation-experiment
cd pdf-generation-experiment
pnpm i
pnpm nx run-many --target=serve --projects=pdf-server,ui-app

After running these commands, you can then use the app to do the actions listed above.

What's next?

Better page break management
PDF / Image compression
Exploring issues faced with fonts
Dockerization
starting the server with only one instance of puppeteer

React and Puppeteer: Pdf generation (pdf generation api)

Layton Whiteley — Sun, 02 Oct 2022 13:43:08 +0000

Generating the PDF

Goals:

Generate a pdf server-side
return the PDF file to the caller

Step 1

Lets create some helpers

We need a helper to render a full html document to register fonts and interpolate the body of the pdf

// file: apps/pdf-server/src/pdf/helpers/render-pdf-document.ts

import { Font, PDFData } from '@pdf-generation/constants';

const renderFontFaces = (font: Font) => {
  return (
    font?.fontFaces?.map((fontFace) => {
      const family = font.family ? `font-family: ${font.family};` : '';
      const style = fontFace.style ? `font-style: ${fontFace.style};` : '';
      const weight = fontFace.weight ? `font-weight: ${fontFace.weight};` : '';
      const format = fontFace.format ? `format(${fontFace.format})` : '';

      return `
        @font-face {
          ${family}
          ${style}
          ${weight}
          src: url(${fontFace.src}) ${format};

        }
      `;
    }) || ''
  );
};

export const renderPdfDocument = (data: PDFData, body: string) => {
  const font = renderFontFaces(data.font);

  return `
    <html>
      <head>
        <meta charset="utf-8" />
        <title>${data.metadata.title}</title>
        <meta name="viewport" content="width=device-width, initial-scale=1" />

        <style>
            ${font}
            body {
                -webkit-print-color-adjust: exact !important;
                color-adjust: exact !important;
                print-color-adjust: exact !important;
            }

        </style>
      </head>
      <body>
        ${body}
      </body>
    </html>
    `;
};

Now we need a helper to set the metadata of the PDF file. Puppeteer, unfortunately, has no way to specify the metadata one may need. Therefore, we use pdf-lib below to set this metadata and return a Buffer for further use

import { PDFDocument } from 'pdf-lib';

const metadataSetters = {
  title: 'setTitle',
  author: 'setAuthor',
  creator: 'setCreator',
  producer: 'setProducer',
  subject: 'setSubject',
};

export async function setPdfMetadata(pdf: Buffer, metadata) {
  const setterEntries = Object.entries(metadataSetters);

  if (!setterEntries.some(([key]) => !!metadata[key])) return pdf;

  const document = await PDFDocument.load(pdf);

  setterEntries.forEach(([key, setter]) => {
    const value = metadata[key];
    if (value) document[setter](value);
  });

  const pdfBytes = await document.save();

  return Buffer.from(pdfBytes);
}

Lets also define a font we want to use

export const DEFAULT_PDF_FONT = {
  family: 'Open Sans',
  familyDisplay: "'Open Sans', sans-serif",
  fontFaces: [
    {
      src: 'https://fonts.gstatic.com/s/opensans/v18/mem5YaGs126MiZpBA-UN_r8-VeJoCqeDjg.ttf',
      weight: 300,
    },
    {
      src: 'https://fonts.gstatic.com/s/opensans/v18/mem8YaGs126MiZpBA-U1UpcaXcl0Aw.ttf',
    },
    {
      src: 'https://fonts.gstatic.com/s/opensans/v18/mem6YaGs126MiZpBA-UFUJ0ef8xkA76a.ttf',
      style: 'italic',
    },
    {
      src: 'https://fonts.gstatic.com/s/opensans/v18/mem5YaGs126MiZpBA-UNirk-VeJoCqeDjg.ttf',
      weight: 600,
    },
    {
      src: 'https://fonts.gstatic.com/s/opensans/v18/memnYaGs126MiZpBA-UFUKXGUehsKKKTjrPW.ttf',
      weight: 600,
      style: 'italic',
    },
  ],
};

Step 2

Lets create the service that will do the work.

// file: apps/pdf-server/src/pdf/pdf.service.ts

import { Injectable } from '@nestjs/common';
import * as puppeteer from 'puppeteer';
import { writeFile } from 'fs/promises';

import { PDFDocumentData } from '@pdf-generation/constants';
import { PdfDocProps, renderPdfDoc } from '@pdf-generation/pdf-doc';
import { environment } from '../environments/environment';
import { renderPdfDocument, setPdfMetadata, DEFAULT_PDF_FONT } from './helpers';

@Injectable()
export class PdfService {
  async generatePdf(data: PDFDocumentData<PdfDocProps>) {
    const browser = await puppeteer.launch({
      /**
       * Adding `--no-sandbox` here is for easier deployment. Please see puppeteer docs about
       * this argument and why you may not want to use it.
       */
      args: [`--no-sandbox`],
    });

    const pdfData = {
      ...data,
      font: data.font ?? DEFAULT_PDF_FONT,
    };

    const documentBody = renderPdfDoc(pdfData.document, pdfData.font);
    const content = renderPdfDocument(pdfData, documentBody);
    const pdfOptions = pdfData?.options || {};

    const page = await browser.newPage();
    await page.setContent(content, {
      waitUntil: 'networkidle2',
    });
    const pdf = await page.pdf({
      format: 'a4',
      printBackground: true,
      preferCSSPageSize: true,
      ...pdfOptions,
      margin: {
        left: '40px',
        right: '40px',
        top: '40px',
        bottom: '40px',
        ...(pdfOptions?.margin || {}),
      },
    });

    // Give the buffer to pdf-lib
    const result = await setPdfMetadata(pdf, pdfData?.metadata);

// write to disk for debugging
    if (!environment.production) {
      const now = Date.now();
      const filePath = `${environment.tmpFolder}/${now}-tmp-file.pdf`;
      await page.screenshot({
        fullPage: true,
        path: `${environment.tmpFolder}/${now}-tmp-file.png`,
      });
      await writeFile(filePath, result);
    }

    await browser.close();

    return result;
  }
}

Now whats happening here?

We are opening a headless chromium browser
We render the content of the pdf we generate with renderPdfDoc
We render the full html document with renderPdfDocument
We set the metadata with setPdfMetadata if available
We close the browser then return the Buffer

Step 3

Now we need to wire up the service so its accessible by updating the Controller

// file: apps/pdf-server/src/pdf/pdf.controller.ts

import { Body, Controller, Post } from '@nestjs/common';
import { PdfService } from './pdf.service';

@Controller('pdf')
export class PdfController {
  constructor(private service: PdfService) {}

  @Post('/generate')
  async generatePdf(@Body() data) {
    return this.service.generatePdf(data);
  }
}

Step 4

Now finally, wire up the PDF module to the app.

in apps/pdf-server/src/app/app.module.ts

Add PdfModule to the imports array

@Module({
  imports: [PdfModule], // <== here
  controllers: [AppController],
  providers: [AppService],
})

Thats it!

Now you can test the api by starting it

pnpm nx run pdf-server:serve

curl --location --request POST 'localhost:3333/api/pdf/generate' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "sample",
    "metadata": {
        "title": "Some random pdf",
        "subject": "Some radom pdf",
        "author": "Statale",
        "producer": "pdf-generation-server",
        "creator": "My awesome creator"
    },
    "document": {
        "images": [
            {
                "id": 0,
                "url": "https://source.unsplash.com/category/technology/1600x900"
            },
            {
                "id": 1,
                "url": "https://source.unsplash.com/category/current-events/1600x900"
            }
        ],
        "title": "Some random pdf",
        "description": "<p>Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat,...</p>"
    }
}'

React and Puppeteer: Pdf generation (create pdf-doc view)

Layton Whiteley — Sun, 02 Oct 2022 13:42:50 +0000

Before creating the service to render the pdf, we first need the pdf view.

Goals

Ability to render rich text content
Render SVG components
Render images
Render content using layout stying (columns etc.)
Specifying a custom font

To achieve these goals we installed a few libraries in the previous article.

These were:

chakra ui
interweave

Create the view

Step 1

First, lets create a RichText component which will be reusable to display richtext content. For the purposes of the experiment, this is the only specialized component we will need. All other useful components will come from chakra ui

// file: libs/pdf-doc/src/lib/components/rich-text.tsx

import { Box, BoxProps } from '@chakra-ui/react';
import { Markup } from 'interweave';

interface RichTextProps extends BoxProps {
  content: string;
}

export const RichText = ({ content, ...props }: RichTextProps) => {
  return (
    <Box
      {...props}
      sx={{
        p: {
          fontSize: '12px',
          marginBottom: '8px',
        },
        li: {
          fontSize: '12px',
          paddingLeft: '16px',
        },
        ol: {
          paddingInlineStart: '20px',
          mb: '20px',
        },
        ul: {
          paddingInlineStart: '20px',
          mb: '20px',
        },
      }}
    >
      <Markup content={content} />
    </Box>
  );
};

Step 2

Lets create some sample data and types for our template

Note: The data is truncated. See the repository for full example

// file: libs/constants/src/lib/constants.ts

export const samplePdfData = {
  images: [
   // this is playful, images will be different per render
'https://source.unsplash.com/category/technology/1600x900',
    'https://source.unsplash.com/category/nature/1600x900',
    'https://source.unsplash.com/category/sports/1600x900',
    'https://source.unsplash.com/category/bike/1600x900',
    'https://source.unsplash.com/category/dogs/1600x900',
    'https://source.unsplash.com/category/cats/1600x900',
  ].map((image, index) => ({ id: index, url: image })),
  title: 'Some random pdf',
  description:
    '<p>Duis autem vel eum iriure dolor in...</p>...',
};

// file: libs/constants/src/lib/types.ts

import { PDFOptions } from 'puppeteer';

export interface PDFMetadata {
  title: string;
  subject: string;
  author: string;
  producer: string;
  creator: string;
}

export interface Font {
  familyDisplay: string;
  family: string;
  fontFaces?: {
    style?: string;
    weight?: number;
    format?: string;
    src: string;
  }[];
}

export interface PDFData {
  id: string | number;
  metadata: PDFMetadata;
  options?: PDFOptions;
  font: Font;
}

export interface PDFDocumentData<T> extends PDFData {
  document: T;
}

Note: ensure both files are exported by the library

Step 3

Create a story to help develop the view

// file: libs/pdf-doc/src/lib/pdf-doc.stories.tsx

// to run the instance:
// pnpm nx run pdf-doc:storybook 

import { Meta, Story } from '@storybook/react';
import { samplePdfData } from '@pdf-generation/constants';
import { PdfDoc, PdfDocProps } from './pdf-doc';

export default {
  component: PdfDoc,
  title: 'Components/PdfDoc',
} as Meta;

const Template: Story<PdfDocProps> = (args: PdfDocProps) => {
  return <PdfDoc {...args} />;
};

export const DefaultExample = Template.bind({});

DefaultExample.args = samplePdfData;

Step 4

Create your pdf view. This part is totally up to you but see the final pdf component for this experiment.
Also for more details check the repository.

import { Box, Heading, Stack, Text } from '@chakra-ui/react';
import { CustomSvg } from './components/custom-svg';
import { Icons } from './components/icons';
import { Images } from './components/images';
import { RichText } from './components/rich-text';
import { SectionTitle } from './components/section-title';
import { ImageData } from './pdf-doc.types';

export interface PdfDocProps {
  images: ImageData[];
  title: string;
  description: string;
}

export function PdfDoc(props: PdfDocProps) {
  const { title, description, images } = props;
  return (
    <Stack spacing={6} fontSize="md">
      <Heading as="h1" size="4xl" color="blue.800">
        {title}
      </Heading>
      <Stack spacing={3}>
        <Text>This is normal text</Text>

        <Heading as="h3" size="l" color="blue.200">
          Description (rich text)
        </Heading>
        <RichText content={description} />
      </Stack>

      <SectionTitle>Images</SectionTitle>
      <Images items={images} />

      <SectionTitle>Icons</SectionTitle>
      <Icons />

      <SectionTitle>Custom Svg</SectionTitle>
      <Box fontSize="200px">
        <CustomSvg />
      </Box>
    </Stack>
  );
}

Step 5

Create a function to render the pdf view as a string and ensure it is exported in index.ts

// file: libs/pdf-doc/src/lib/pdf-doc.server.tsx

import { renderToString } from 'react-dom/server';
import {
  ChakraProvider,
  extendTheme,
  theme as chakraTheme,
} from '@chakra-ui/react';
import { Font } from '@pdf-generation/constants';
import { PdfDoc, PdfDocProps } from './pdf-doc';

export const renderPdfDoc = (data: PdfDocProps, font?: Font) => {
  const fontFamilyDisplay =
    font?.familyDisplay || font?.family;

  return renderToString(
    <ChakraProvider
      theme={extendTheme({
        fonts: {
          ...chakraTheme.fonts,
          body: fontFamilyDisplay || chakraTheme.fonts.body,
          heading: fontFamilyDisplay || chakraTheme.fonts.heading,
        },
      })}
    >
      <PdfDoc {...data} />
    </ChakraProvider>
  );
};

Thats it!

Now to create the controller for generating the pdf

React and Puppeteer: Pdf generation (project setup)

Layton Whiteley — Sun, 02 Oct 2022 13:42:29 +0000

Summary

This is an experimentation detailing how to generate pdf documents using a server and React as the template engine.

Why

I have used @react-pdf/renderer in the past and this aims to solve a few issues I had with it

Issues

Limited set of components to work with
Maintenance has slowed down, therefore, the future outlook doesnt look bright for unresolved issues
Currently the library does not work with react 18 so this makes it difficult to upgrade an application to react 18

Goals

Decouple pdf generation from the client application
Have a simple server process to generate PDF documents
Keep using React as a familiar library for UI development
Only critical coding steps will be detailed, please check the final source code if something is missing in the steps

Why not just do it in the user's browser/client?

This is meant for use cases where there needs to be a repeatable process
In this scenario, simply creating print styles doesnt work as the view needed for the pdf is not necessarily what is being viewed in the client
user could be using a mobile application

Note: The goals, libraries and specific data flows used for the experiment are purely subjective as not every use case will need to do all these steps. Mainly focus on how the pdf is generated.

Technology

React: use as a template engine. any other templating engine can be used
- chakra ui: used as a ui library. not needed but has a lot of simple to use components for a demo. alternatives ca be used
- storybook: used as a ui development assistant library. not needed but good to use to develop the view/pdf visually
Puppeteer: used as an in place html renderer and orchestrator: alternatives can also be used
nx: used for project management. We will create multiple projects in the same repository. Nx makes this easier to link up all projects. Alternatives can be used

TL;DR;

view the full project on github:
https://github.com/lwhiteley/pdf-generation-experiment

git clone https://github.com/lwhiteley/pdf-generation-experiment
cd pdf-generation-experiment
pnpm i
pnpm nx run-many --target=serve --projects=pdf-server,ui-app

After running these commands, you can then use the app experience the full solution.

Setup

Create project + Install dependencies

npx create-nx-workspace --pm pnpm pdf-generation
# ? Enable distributed caching to make your CI faste: No

cd pdf-generation
pnpm add -D @nrwl/react @nrwl/nest @nrwl/storybook @nrwl/node
pnpm add pdf-lib puppeteer utf-8-validate sharp
pnpm add @chakra-ui/react @emotion/react @emotion/styled framer-motion @chakra-ui/icons @chakra-ui/styled-system use-debounce axios
pnpm add -D @chakra-ui/storybook-addon
pnpm add interweave interweave-ssr

Generate the projects we will work with

pnpm nx g @nrwl/react:application ui-app
  # Choose: emotion
  # use router: Yes

pnpm nx g @nrwl/nest:application pdf-server

pnpm nx g @nrwl/node:library constants

pnpm nx g @nrwl/react:library pdf-doc

pnpm nx g @nrwl/storybook:configuration pdf-doc
  # Choose: @storybook/react

Notes:

Ensure to add the chakra ui storybook plugin
docs: https://chakra-ui.com/getting-started/with-storybook

Configure pdf-server for React and deployment

Move @babel/core to dependencies in package.json
in apps/pdf-server/project.json
- set targets.build.options.generatePackageJson: true
- essentially adding: "generatePackageJson": true in the specified location of the json file
Copy .babelrc file from ui-app and place it into the pdf-server root folder
Add "jsx": "react-jsx" in
- apps/pdf-server/tsconfig.app.json
- apps/pdf-server/tsconfig.spec.json

Create a file at the same level of apps/pdf-server/src/main.ts

// file: dependencies.register.ts

/**
 * We import dependencies that are missed by nx auto package.json creation
 */

import '@babel/core';
import '@emotion/styled';
import '@chakra-ui/styled-system';
import 'utf-8-validate';
import { polyfill } from 'interweave-ssr';

// view this file for environment config
import { environment } from './environments/environment';

polyfill();

// this could be moved to a helper library
export const createDirectory = (directory: string) => {
  if (existsSync(directory)) return false;
  mkdirSync(directory, { recursive: true });
  return true;
};

createDirectory(environment.tmpFolder);

Then import it in main.ts

import './dependencies.register.ts'

Create nestjs pdf module

pnpm nx g @nrwl/nest:module pdf --project=pdf-server
pnpm nx g @nrwl/nest:controller pdf --project=pdf-server
pnpm nx g @nrwl/nest:service pdf --project=pdf-server

Proxy the `pdf-server` to `ui-app`

Create a file apps/ui-app/proxy.config.json

{
  "/api": {
    "target": "http://localhost:3333/api",
    "pathRewrite": { "^/api": "" },
    "secure": false,
    "logLevel": "debug"
  }
}

then in apps/ui-app/project.json

add the following to targets.serve.configurations.development

"proxyConfig": "apps/ui-app/proxy.config.json",
"open": true

Now that we've gotten the setup done its time to write some code

Advanced Large Object Management with jotai

Layton Whiteley — Sun, 26 Sep 2021 21:10:11 +0000

Getting Started

This article assumes the following knowledge:

Basic understanding of jotai
You have seen the Large Object concept on the official jotai documentation

Goal

Understand how to focus on deeply nested parts of a large object
Not repeat what jotai library already explains

TLDR;

full code example:

https://codesandbox.io/s/pensive-fast-89dgy?file=/src/App.js

Introduction

Managing large objects is sometimes necessary when dealing with structured client state. For eg. managing a very sophisticated tree or maybe a content editor. Jotai makes this very simple with its various utilities and plugins to manage state.

Utilities and tools that will be discussed in this article:

focusAtom (jotai/optic-ts integration) - create a read-write derived atom based on a predicate
splitAtom (jotai utility) - transform a data array into an array of atoms
selectAtom (jotai utility) - create a read-only atom based on a predicate

Challenges with managing large objects with only react

Managing updates to specific parts that are deeply nested and reporting the change back to the main object
Managing deeply nested callbacks and also changing the data manually with setters, spreading, you name it!

None of the challenges listed above are inherently bad but when a developer does repetitive work, the thought always comes to mind about how all this boilerplate can be abstracted away.

Luckily jotai has a nice solution to these challenges.

Let’s talk about doing this the jotai way.

For this article we will be managing a cat! Yes...meow! The application will tell a Vet if specific body parts of the cat are injured.

Please note the object shape below is not necessarily how you would do this in a real application but designed to give a good example for the purposes of this article

Now what will our cat injury data look like?

{
 "name": "Sparkles",
 "owner": { "id": 1, "firstName": "John", "lastName": "Doe" },
 "parts": [
   {
     "type": "legs",
     "attributes": [
       { "placement": "front-left", "injured": false },
       { "placement": "front-right", "injured": false },
       { "placement": "back-left", "injured": false },
       { "placement": "back-right", "injured": true }
     ]
   },
   {
     "type": "tail",
     "attributes": [{ "injured": true }]
   },
   {
     "type": "ears",
     "attributes": [
       { "placement": "left", "injured": false },
       { "placement": "right", "injured": true }
     ]
   }
 ]
}

First let's understand two types of state within large objects and how to access them

View only state

For state that we only need to view, we can use the selectAtom to access them. The selectAtom will give you a read-only atom that works well for this scenario.

Editable state

For state that we need to edit, we can use the focusAtom to literally focus on these sections and edit them without large callbacks to merge the data back into the main object.

Jotai documentation already explains how to go at least one level deep, so the question you may ask is, how do we get to the nested arrays like the cat’s attributes and manage the data individually?

You may be tempted to split the attributes array using splitAtom, however, splitAtom only creates atoms from raw data and this data has no way of knowing how to report itself back to the root node.

So how do we update each “cat attribute” without managing the entire array ourselves?

The trick lies within the optic-ts integration.

You can focus on array indexes using the at(index) function which keeps an established reference to the root node.

See code example below.

const useAttributeAtom = ({ attributesAtom, index }) => {
 return useMemo(() => {
   return focusAtom(attributesAtom, (optic) => optic.at(index));
 }, [attributesAtom, index]);
};

const Attribute = ({ attributesAtom, index }) => {
 const attributeAtom = useAttributeAtom({ attributesAtom, index });
 const [attribute, setAttribute] = useAtom(attributeAtom);

 return (
   <div style={{ display: "flex" }}>
     <label>
       <span style={{ marginRight: "16px" }}>
         {attribute.placement}
       </span>
       <Switch
         onChange={(checked) =>
           setAttribute((prevAttribute) => ({
             ...prevAttribute,
             injured: checked
           }))
         }
         checked={attribute.injured}
       />
     </label>
   </div>
 );
};

See the full code example

What did we achieve?

We were able to change focused pieces of the large object without deep prop drilling of any onChange functions
We managed “global” state within the application while keeping the interfaces resembling React.

Important Tips!

The starting atom (root node) must be a writable atom. This helps when derived atoms need to write back changed information
Atoms created within a render should be memoized or else you will have too many re-renders and most likely React will throw an error stating this exactly.

Thanks for reading!

Have you had this problem before?

Let me know if you have done this with jotai before and what solutions you came up with.

Always looking to learn more!

Forem: Layton Whiteley

Using vanilla-extract in an nx workspace (webpack)

Overview

What is vanilla-extract?

Setup

Let's create a workspace

Install dependencies

Create custom webpack config

Use the custom webpack config

Create and use your styles

Run the application

Your next steps

React and Puppeteer: Pdf generation (client download and print)

Summary

Setup UI

Step 1

React and Puppeteer: Pdf generation (pdf generation api)

Generating the PDF

Step 1

Step 2

Step 3

Step 4

React and Puppeteer: Pdf generation (create pdf-doc view)

Goals

Create the view

Step 1

Step 2

Step 3

Step 4

Step 5

React and Puppeteer: Pdf generation (project setup)

Summary

Why

Issues

Goals

Why not just do it in the user's browser/client?

Technology

TL;DR;

Setup

Create project + Install dependencies

Generate the projects we will work with

Configure pdf-server for React and deployment

Create nestjs pdf module

Proxy the pdf-server to ui-app

Advanced Large Object Management with jotai

Getting Started

Goal

TLDR;

Introduction

What did we achieve?

Important Tips!

Proxy the `pdf-server` to `ui-app`