DEV Community: TimJ

The Best ESLint Rules for React Projects

TimJ — Sat, 16 Sep 2023 03:56:47 +0000

Using ESLint for React projects can help catch some common mistakes, code-smells, and define common conventions for a codebase. In this blog, I'll go through some valuable ESLint plugins and rules tailored specifically for React projects.

Note that this blog is oriented towards usage of React in TypeScript with functional components. It also assumes you've already sorted your base ESLint/TypeScript/Prettier configs.

You can find my complete ESLint config on NPM: @tim-w-james/eslint-config

Official React Plugin

An obvious pick for React projects, but eslint-plugin-react along with their plugin:react/recommended rule set is a must. This will give you some sensible rules such as requiring a key to be specified in JSX arrays. eslint-config-airbnb is another good (if a bit loose) base rule set on top of eslint-plugin-react to start from.

I've tweaked the recommended rule set in a few ways:

"react/prefer-stateless-function": "error",
"react/button-has-type": "error",
"react/no-unused-prop-types": "error",
"react/jsx-pascal-case": "error",
"react/jsx-no-script-url": "error",
"react/no-children-prop": "error",
"react/no-danger": "error",
"react/no-danger-with-children": "error",
"react/no-unstable-nested-components": ["error", { allowAsProps: true }],
"react/jsx-fragments": "error",
"react/destructuring-assignment": [
  "error",
  "always",
  { destructureInSignature: "always" },
],
"react/jsx-no-leaked-render": ["error", { validStrategies: ["ternary"] }],
"react/jsx-max-depth": ["error", { max: 5 }],
"react/function-component-definition": [
  "warn",
  { namedComponents: "arrow-function" },
],
"react/jsx-key": [
  "error",
  {
    checkFragmentShorthand: true,
    checkKeyMustBeforeSpread: true,
    warnOnDuplicates: true,
  },
],
"react/jsx-no-useless-fragment": "warn",
"react/jsx-curly-brace-presence": "warn",
"react/no-typos": "warn",
"react/display-name": "warn",
"react/self-closing-comp": "warn",
"react/jsx-sort-props": "warn",
"react/react-in-jsx-scope": "off",
"react/jsx-one-expression-per-line": "off",
"react/prop-types": "off",

Some notable rules in the above config:

react/no-unstable-nested-components: components with components are an anti-pattern since they lose state when their parent is re-rendered (not to mention poor readability).
react/destructuring-assignment: this one is partially to enforce consistent code style, but also encourages you to make your state dependencies more efficient (rather than blindly passing in props).
react/jsx-no-leaked-render: prefer conditional rendering via ternary expressions - an easy win to avoid unexpected values being rendered from && or even crashes in rare cases.
react/jsx-max-depth: as soon as your components start reaching too far to the right, you know they're getting too big.
react/function-component-definition: standardise how you define your functional components.
react/jsx-no-useless-fragment + react/jsx-fragments: more consistent JSX fragments.
react/no-children-prop: improves readability for wrapper components.
react/no-unused-prop-types: flags any unused types. Note this has some limitations, as it won't flag props defined via the React.FC<PropTypes> generic.
react/no-danger: just in case a prop called dangerouslySetInnerHTML isn't enough to discourage it's use.
react/display-name: no anonymous function components for better maintainability and integration with React's debugging tools.

Depending on your project, you might want to consider some of the following stricter rules:

react/prefer-read-only-props: enforce immutability in your prop types.
react/no-array-index-key: define better keys to avoid unnecessary re-renders.
react/jsx-no-bind: has performance benefits, preventing functions declared in a component from being created again on every re-render.
react/jsx-props-no-spreading: helps with maintainability, readability and reduces the risk of invalid HTML props being passed to elements. However, I still believe spreading props has great utility for certain use-cases such as wrapper components, so use your own judgement on this one.
react/no-multi-comp: one component per file. In my opinion, this isn't always ideal, especially for components with very specific uses that shouldn't be exposed to the wider codebase, but this can be mitigated somewhat by a good folder structure.

Rules of Hooks

react-hooks with the plugin:react-hooks/recommended rule set will save you more than a few headaches. Importantly, you can't call hooks conditionally, and will be warned if you state dependencies aren't exhaustive.

React Refresh

react-refresh. Requires that .tsx/.jsx files only export components. Why? Because this optimises your app for fash refresh to get a smoother development experience. If you're using Vite, you'll be utilising fash refresh under the hood and will want to enable this rule.

Turn it on with the config:

"react-refresh/only-export-components": "warn",

JSX Ally

jsx-a11y is all about ensuring your DOM elements are accessible. This plugin will prompt you to include the correct ARIA attributes such as labels and roles, in addition to things like alt text.

The jsx-a11y/recommended ruleset has reasonable defaults, though ensure you map your custom components to DOM elements.

As an aside - as much as engineers like automated tooling, it will only get you so far in the world of accessibility. Using this plugin along with Lighthouse or additional A11y plugins for your E2E testing framework of choice is recommended, since that will help you identify additional issues like colour contrast (I'd suggest including these checks into your CI workflows). But ultimately, static accessibility analysis will help you identify basic mistakes, but isn't a substitute for some thorough manual testing for keyboard-only, screen reader, etc. usability (even better - get your target end-users involved in the process or seek an accessibility audit).

Naming Conventions and Filename Rules

By convention, React components should be named in PascalCase. @typescript-eslint has the config we need, and though we can't specifically target React components, we can target variables (and set some other conventions while we're at it):

"@typescript-eslint/naming-convention": [
  "warn",
  {
    selector: "default",
    format: ["camelCase"],
    leadingUnderscore: "allow",
  },
  {
    selector: "variable",
    // Specify PascalCase for React components
    format: ["PascalCase", "camelCase"],
    leadingUnderscore: "allow",
  },
  {
    selector: "parameter",
    format: ["camelCase"],
    leadingUnderscore: "allow",
  },
  {
    selector: "property",
    format: null,
    leadingUnderscore: "allow",
  },
  {
    selector: "typeLike",
    format: ["PascalCase"],
  },
],

Then we can enforce our file names to be PascalCase via filename-rules:

"filename-rules/match": [2, { ".ts": "camelcase", ".tsx": "pascalcase" }],

Finally, I'd also suggest requiring named exports via import:

"import/no-default-export": "error",

TS/JSDoc

We want to ensure our React components (and code more generally) is well documented. Using jsdoc we can specify formatting requirements for our documentation, with tsdoc for some TS specific syntax.

Extend jsdoc/recommended-typescript and specify some extra config:

"jsdoc/require-throws": "error",
"jsdoc/check-indentation": "warn",
"jsdoc/no-blank-blocks": "warn",
"jsdoc/require-asterisk-prefix": "warn",
"jsdoc/require-description": "warn",
"jsdoc/sort-tags": "warn",
"jsdoc/check-syntax": "warn",
"jsdoc/tag-lines": ["warn", "never", { startLines: 1 }],
"jsdoc/require-param": ["warn", { checkDestructuredRoots: false }],
"jsdoc/require-jsdoc": [
  "warn",
  {
    publicOnly: true,
    require: {
      FunctionDeclaration: true,
      FunctionExpression: true,
      ArrowFunctionExpression: true,
      ClassDeclaration: true,
      ClassExpression: true,
      MethodDefinition: true,
    },
    contexts: [
      "VariableDeclaration",
      "TSTypeAliasDeclaration",
      // Encourage documenting React prop types
      "TSPropertySignature",
    ],
    enableFixer: true,
  },
],
// tsdoc checks this syntax instead
"jsdoc/require-hyphen-before-param-description": "off",
"jsdoc/require-returns": "off",

"tsdoc/syntax": "warn",

This requires our exported components to be documented. Note that this has some limitations - in an ideal world we'd want prop types to be documented like so:

type MyComponentProps = {
  /**
   * Some prop does something.
   */
  someProp: string;
};

/**
 * My component does a thing.
 */
export const MyComponent = ({ someProp }: MyComponentProps) => {
  ...
};

We extract our prop type definitions into their own type, then document each prop individually. This integrates with VSCode to display the description of someProp and is much cleaner than trying to document the destructured params.

However, the jsdoc ESLint plugin doesn't allow you to specify different requirements for different contexts depending on whether they are exported or not. We can use TSPropertySignature, but unless the prop types are exported, the rule won't be triggered. Feel free to reach out if you're aware of a solution to this limitation.

Bonus - Arrow Function Styles

I prefer to set a standard for function declarations, so require use of arrow functions with an implicit return if possible. prefer-arrow-functions can do this for us, noting we also need to override some default ESLint rules:

"prefer-arrow-functions/prefer-arrow-functions": [
  "warn",
  {
    classPropertiesAllowed: true,
    disallowPrototype: true,
    returnStyle: "unchanged",
  },
],
"arrow-body-style": "warn",
"prefer-arrow-callback": [
  "warn",
  {
    allowNamedFunctions: true,
  },
],

Wrapping Up

Using the rules above will improve your code quality, consistency, and reduce the risk of bugs. However, every project is different and every team has their own styles and conventions, so I'd suggest tweaking rules to your needs. With that said, it's better to start with a stricter rule set then loosen it to reduce any false positives or noise. This encourages you to think critically about the code you write, and make the conscious decision to ignore rules if you need rather than be ignorant to certain anti-patterns.

My custom ESLint rule set applies the insights from this blog and can be installed via NPM: @tim-w-james/eslint-config. It also includes many useful ESLint and TypeScript rules that aren't specific to React.

Contributions and suggestions for extra rules are welcome.

Creating a Site Builder with NextJS and Sanity CMS

TimJ — Sun, 18 Jun 2023 14:00:00 +0000

Using a headless CMS provides developers with the flexibility they need, and exposes a user-friendly interface to clients that allows them to manage their own content. In this post, I'll go through the configuration of an SEO optimised app backed by a site builder with a realtime editor preview, achieved with NextJS and Sanity CMS.

Overview

We'll be extending the NextJS + SanityCMS blog starter, which gives us the following:

Static site generation via Next js for a performant and SEO friendly site.
Content is defined using a headless CMS (Sanity.io).
Users can interact with the CMS via Sanity Studio deployed to https://SITE_URL/studio:
- Draft mode with a side-by-side preview in Sanity Studio or live at https://SITE_URL/api/preview.
- Secured by Sanity's build in auth.
- Real-time collaboration.
- Version history for published data.
Incremental Static Revalidation via a webhook-trigger to publish new site content.

Instead of a blog, we'll be updating the schema to allow users to create their own general static site.

Including:

Any number of pages for their site:
- Define content using a rich text editor:
- Basic markdown-style formatting (headers, lists, links, etc.)
- Embed files, PDFs, and images which are optimisied and served by NextJS.
- SEO title and description
Custom nav bar with configurable routes for each page:
- Uses NextJS's routing to provide optimised code splitting and client-side routing after the initial load.
- Support for nested routes.

We'll be using Sanity Studio, which will provide our users with an interface to interact with the CMS and customise their site. Unlike other SaaS site builders, Sanity themselves don't host or manage Sanity Studio, it is essentially just a React app that uses their API. This means we can configure the studio however we want, and we are far less constrained than a service like SquareSpace or Wix. We'll be deploying the studio along side the app itself, at the /studio path.

Defining the Entity Structure

We first need to customise how we handle each type of top-level entity in Sanity Studio. We have 3 kinds:

"Documents" - multiple instances of an entity with their own configuration (pages):
- Display these in a list, where each page automatically opens a preview showing that specific page.
- Supporting the ability to create/delete each document.
"Singletons" - global config where only 1 can exist (settings for the site title, nav, etc.):
- Need to make sure only 1 of these entities exist, so disable creation/deletion.
"Singleton with preview" - it makes sense to display a preview for certain singletons (the home page, since we need to ensure that exists at the root path).

This is achieved in sanity.config.ts. The previewStructurePlugin function places the 2 variants of singletons Sanity Studio sidebar and configures the preview as needed. We also need to remove them from the global "new document" button, so we pass them to singletonPlugin, then add the "open preview" button to the desired preview singletons via productionUrl. All the other documents (just pages here) go to previewDocumentNode.

Defining the Schemas

You can browse the source code for the schemas I'll be discussing here, and check Sanity's documentation if you want to add your own.

Pages

First, define a page schema:

export default defineType({
  name: "pages",
  title: "Pages",
  icon: DocumentsIcon,
  type: "document",
  preview: {
    select: { title: "metadata.title", subtitle: "metadata.description" },
  },
  fields: [
    defineField({
      name: "metadata",
      title: "Metadata",
      type: "pageMeta",
      validation: (rule) => rule.required(),
    }),
    defineField({
      name: "content",
      title: "Content",
      type: "page",
    }),
  ],
});

View full source

A document type is the fundamental building block of Sanity, which allows us to configure arbitrary fields. I've split this into two field 'groups' - metadata (title, URL path, etc.), and the page content itself. We also infer the preview information (which appears in Sanity Studio) from the metadata.

The metadata schema is as follows:

export default defineType({
  name: "pageMeta",
  title: "Page Metadata",
  icon: DocumentsIcon,
  type: "object",
  preview: { select: { title: "title", subtitle: "description" } },
  fields: [
    defineField({
      name: "title",
      title: "Page Title",
      description: "Appears in the browser tab and search results.",
      type: "string",
      validation: (rule) => rule.required(),
    }),
    defineField({
      name: "description",
      description: "Appears in search results.",
      title: "Description",
      type: "string",
      validation: (rule) => rule.max(155),
    }),
    defineField({
      name: "path",
      title: "Path",
      description: `Used for the URL path: https://example.com/your-path`,
      type: "slug",
      options: {
        source: "metadata.title",
        isUnique: (value, context) => context.defaultIsUnique(value, context),
      },
      validation: (rule) => rule.required(),
    }),
  ],
});

View full source

We have a few standard fields here, which you can read more about here. The path is the more interesting one:

Type slug ensures that the path is unique (since it'll be part of the URL) across other pages, and has a valid format.
We infer the default value from the title, which is automatically converted into a valid format for the slug.

Now to define the content:

export default defineType({
  name: "page",
  title: "Page",
  icon: DocumentsIcon,
  type: "object",
  preview: { select: { title: "header" } },
  fields: [
    defineField({
      name: "header",
      title: "Header",
      description: "Appears at the top of the page.",
      type: "string",
    }),
    defineField({
      name: "body",
      title: "Body",
      description:
        "Rich text content, including sub headings, links, images, and PDFs.",
      ...
    }),
  ],
});

Now for the interesting part - we need a way for the user to customise the content of the page in a familiar editor-like experience

Rich Text Blocks

Raw markdown is an option, but instead we'll be using portable text to support some custom object types.

Out of the box, Sanity gives us a block type for rich text. That gives us basic formatting options (decorators like bold, italics, etc.), but we want to extend this with a few things. You can follow along with the source code here. It must be used with an array so we can define custom objects to appear within the page:

defineField({
  name: "body",
  title: "Body",
  description:
    "Rich text content, including sub headings, links, images, and PDFs.",
  type: "array",
  of: [
    {
      type: "block",
      marks: {
        ...
      },
    },
    ...
  ],
}),

We'll tackle links first, allowing the user to highlight text, and convert it into a link. We can use annotations, which allow us to create an arbitrary object associated with some text. An annotation for a link to an external URL looks like this:

{
  name: "urlLink",
  type: "object",
  title: "URL Link",
  description: "Link to an external URL.",
  icon: LinkIcon,
  fields: [
    {
      name: "url",
      type: "url",
      title: "URL",
      validation: (rule) => rule.uri().required(),
    },
    {
      name: "hoverText",
      type: "string",
      title: "Description Text",
    },
    {
      name: "shouldUseNewTab",
      type: "boolean",
      title: "Open link in new tab.",
      initialValue: true,
    },
  ],
}

Later, we'll decide how to use these attributes to render this link, but you can imagine how these could translate into an HTML anchor element.

A few things to note:

We provide some helpful descriptions and icons to determine how Sanity Studio displays this object to our user (who doesn't need to be particularly tech savvy).
We also provide some validation for the format of the URL. You can read more about the validation options Sanity provides here.

Similarly, we can create a link for a file:

{
  name: "fileLink",
  type: "object",
  title: "File Link",
  description: "Link pieces of text to a file.",
  icon: DocumentTextIcon,
  fields: [
    {
      name: "file",
      type: "file",
      title: "File Attachment",
      validation: (rule) => rule.required(),
    },
    {
      name: "fileName",
      type: "string",
      title: "File Name",
    },
  ],
},

The file type does a lot of the heavy lifting here, allowing the user to upload a file of their choosing, which Sanity will then serve to the user.

We also want to allow users to embed images in their site. We don't use an annotation for this, since images are independent from text, so it is a separate element in the array of the parent body field:

{
  type: "object",
  name: "embeddedImage",
  title: "Image",
  icon: ImageIcon,
  fields: [
    {
      name: "imageFile",
      type: "image",
      title: "Image File",
      validation: (rule) => rule.required(),
    },
    {
      name: "imageDescription",
      type: "string",
      title: "Description",
      description: "If the image fails to load, this text will appear.",
      validation: (rule) => rule.required(),
    },
    {
      name: "imageWidth",
      type: "number",
      title: "Image Size",
      description:
        "Pixel width of the image, leave empty for auto scaling.",
      validation: (rule) => rule.max(5000).min(10),
    },
    {
      name: "wrapText",
      type: "boolean",
      title: "Wrap Text",
      description: "Wrap text around the image.",
      initialValue: false,
    },
  ],
},

Sanity has a built-in image type too, but we need the user to specify additional fields so we can determine how to render the image in the frontend later.

Let's create an embedded file too:

{
  type: "object",
  name: "embeddedFile",
  title: "File",
  icon: DocumentPdfIcon,
  fields: [
    {
      name: "file",
      type: "file",
      title: "File Attachment",
      validation: (rule) => rule.required(),
    },
    {
      name: "fileName",
      type: "string",
      title: "File Name",
    },
    {
      name: "shouldRenderPdf",
      type: "boolean",
      title: "Render PDF",
      description: "If the file is a PDF, display it on the page.",
      initialValue: true,
    },
    {
      name: "pdfHeight",
      type: "number",
      title: "PDF Display Height",
      description:
        "Height for the PDF display, leave empty for auto scaling.",
      hidden: ({ parent }) => !parent?.shouldRenderPdf,
      validation: (rule) => rule.max(5000).min(50),
    },
  ],
},

We also give the user an option to embed a PDF file, which we'll use to render the PDF within an iframe. Since we have a field that is specific to whether the PDF is rendered or not, we can use the hidden option.

All together, that gives us a rich text editor with some custom objects.

View full source

Defining the Nav

export default defineType({
  name: "navigation",
  title: "Navigation",
  icon: MasterDetailIcon,
  type: "document",
  preview: {
    prepare: () => ({ title: "Navigation" }),
  },
  fields: [
    {
      name: "items",
      title: "Nav Items",
      type: "array",
      of: [
        {
          type: "object",
          name: "menuItem",
          fields: [
            {
              name: "title",
              title: "Title",
              type: "string",
              validation: (rule) => rule.required(),
            },
            {
              name: "routes",
              title: "Routes",
              description:
                "Pages for the nav item. Define multiple routes for a" +
                " dropdown menu.",
              type: "array",
              of: [
                {
                  type: "object",
                  name: "subMenuItem",
                  fields: [
                    {
                      name: "title",
                      title: "Title",
                      description:
                        "If this is your only route, leave blank." +
                        " Otherwise used for the dropdown menu.",
                      type: "string",
                    },
                    {
                      name: "page",
                      title: "Page",
                      type: "reference",
                      to: [{ type: "pages" }],
                      validation: (rule) => rule.required(),
                    },
                  ],
                },
              ],
            },
          ],
        },
      ],
    },
  ],
});

View full source

We want our navbar to support a dropdown for nested routes, so we have 2 levels of arrays. Using reference, the user can easily search for the pages they created.

For the sake of brevity, I'll leave out the other schemas, you can browse them here.

Building Out the React Frontend

With Sanity being a headless CMS, we have the freedom to render our components and style the site however we want. I'll speed through some of the logic here to get to the interesting parts (you can find the general approach in the NextJS + SanityCMS blog starter).

Since we're using NextJS and want static site generation, data from the CMS comes from getStaticProps. Thankfully, this means we don't need to deal with any loading states, since the site will be rendered before it reaches the client. Nice.

A reusable function getStaticPageProps allows us to query the page data for any path. This runs the following query:

export const pageQuery = (path: string) =>
  groq`*[_type == "pages" && metadata.path.current == "${path}"][0]`;

groq is Sanity's custom query language. We won't go into detail for it here, but you can treat it a bit like GraphQL. One useful thing to note: Sanity Studio has a built-in playground called "Vision" which is handy for development.

The page data ultimately ends up as props in the PageLayout component. We also need to know if the page is being viewed as a preview since it that case the site isn't pre-rendered and we need to handle a loading state.

const PageLayout = (props: PageLayoutProps) => {
  const {
    preview,
    loading,
    page: { content, metadata },
    settings,
    routes,
  } = props;

  return (
    <>
      <PageHead pageMeta={metadata} settings={settings} />

      <Layout loading={loading} preview={Boolean(preview)}>
        <Navigation routes={routes} />
        <Container>
          <h1 className={clsx("pt-3")}>{content?.header ?? "Heading"}</h1>
          <hr />
          {content?.body ? (
            <PortableText
              components={PortableTextRenderer}
              value={content.body}
            />
          ) : (
            "Body"
          )}
        </Container>
      </Layout>
    </>
  );
};

We also treat these props as optional, since even though they are required, the user configuring the CMS data in Sanity Studio can view the realtime preview before that data is valid, and it's preferable that they see the empty 'structure' of the site rather than an error. We also don't have type safety for the schema we defined for Sanity, so I've had to define my own types for these props... (more on this later).

The complex part here is PortableText, so let's give into that next.

Portable Text

Remember all those objects we defined for the rich text editor? Now we can decide how to actually render them.

The magic happens in the PortableTextRenderer:

const PortableTextRenderer: PortableTextComponents = {
  marks: {
    em: ({ children }) => <em>{children}</em>,
    strong: ({ children }) => <strong>{children}</strong>,
    u: ({ children }) => <u>{children}</u>,
    code: ({ children }) => <code>{children}</code>,
    urlLink: UrlLink,
    fileLink: FileLink,
  },
  list: {
    bullet: ({ children }) => <ul>{children}</ul>,
    number: ({ children }) => <ol>{children}</ol>,
  },
  listItem: {
    bullet: ({ children }) => <li>{children}</li>,
    number: ({ children }) => <li>{children}</li>,
  },
  block: {
    blockquote: ({ children }) => (
      <blockquote className={clsx("blockquote")}>{children}</blockquote>
    ),
  },
  types: {
    embeddedImage: ImageComponent,
    embeddedFile: FileComponent,
  },
};

Breaking that down piece by piece:

We are essentially defining React components to render
marks (the annotations and decorations for text) wrap children (the text) in some basic HTML like em for bold, etc. This also includes our custom URL and file links.
list, listItem and block map to their HTML counterparts.
Our custom types for images and files.

URL Links

The UrlLink looks like this:

const { url, hoverText, shouldUseNewTab } = parsedUrlResult.data;
return (
  <a
    href={url}
    rel="noreferrer"
    target={shouldUseNewTab ? "_blank" : "_self"}
    title={hoverText}
  >
    {children}
  </a>
);

We map the user defined options from the Sanity schema into a link. Before we do that however, we need to validate the input from the API is what we expect. Again, we don't know if the data specified in preview mode is valid (initially it won't be), and we don't want the preview to crash, instead it should give some visual feedback to the user.

We'll be using zod to do that validation at runtime:

const urlLinkSchema = z.object({
  _key: z.string(),
  _type: z.literal("urlLink"),
  url: z.string(),
  hoverText: z.string().optional(),
  shouldUseNewTab: z.boolean().optional(),
});

...

const parsedUrlResult = urlLinkSchema.safeParse(value);
if (!parsedUrlResult.success) {
  console.error("Url object did not match schema", {
    cause: parsedUrlResult.error,
  });
  return <span className={clsx("text-danger")}>{children}</span>;
}

View full source

Note that we need to be careful our Sanity native validation and frontend validation align here - the user in Sanity Studio shouldn't be able to save their changes and exit draft mode while the frontend is unable to render the content correctly. Unfortunately, Sanity doesn't provide any tooling to generate zod schemas from their native validation, or even type definitions more generally for our frontend to consume, so we have to write them manually. As an aside, this might be my biggest gripe with Sanity overall, type safety is not a priority of theirs unfortunately.

File Links

FileLink is similar, but we need to construct a URL to the file that has been uploaded on Sanity:

const fileData = parsedFileResult.data;
const { fileName } = fileData;
const [_file, id, extension] = fileData.file.asset._ref.split("-");
return (
  <a
    href={`${sanityBaseUrl}/${id}.${extension}?dl=${
      fileName ? encodeURIComponent(fileName) : id
    }.${extension}`}
  >
    {children}
  </a>
);

View full source

Embedded Files and PDFs

Since we give the user the option to embed PDF files, we do this conditionally with an iframe:

const { fileName, shouldRenderPdf, pdfHeight, file } = parsedFileResult.data;
const [_file, id, extension] = file.asset._ref.split("-");
return extension === "pdf" && shouldRenderPdf ? (
  <iframe
    height={pdfHeight}
    src={`${sanityBaseUrl}/${id}.${extension}`}
    title={fileName || "PDF"}
    width="100%"
  />
) : (
  <a
    href={`${sanityBaseUrl}/${id}.${extension}?dl=${
      fileName ? encodeURIComponent(fileName) : id
    }.${extension}`}
  >
    {`${fileName || "file"}.${extension}` || "Download file"}
  </a>
);

View full source

Images

Now for the tricky one: we want to serve the image in an optimised way using NextJS's Image. This gives us:

Size Optimization - Automatically serve correctly sized images for each device, using modern image formats like WebP and AVIF.
Visual Stability - Prevent layout shift automatically when images are loading.
Faster Page Loads - Images are only loaded when they enter the viewport using native browser lazy loading, with optional blur-up placeholders.
Asset Flexibility - On-demand image resizing, even for images stored on remote servers.

while serving the image directly from Sanity does not.

Thankfully, someone has already built a library to do the heavy lifting for us - next-sanity-image - which gives us a few helper functions:

const ImageRenderer: React.FC<{
  image: ImageType;
  isInline: boolean;
  sanityClient: SanityClient;
}> = ({ image, isInline, sanityClient }) => {
  const imageProps = useNextSanityImage(sanityClient, image.imageFile);
  const { width, height } = getImageDimensions(image.imageFile);
  return (
    <Image
      {...imageProps}
      alt={image.imageDescription || ""}
      loading="lazy"
      style={{
        // Display alongside text if image appears inside a block text span
        display: isInline ? "inline-block" : "block",
        float: image.wrapText ? "left" : "none",

        // Avoid jumping around with aspect-ratio CSS property
        aspectRatio: width / height,
      }}
      width={image.imageWidth || width}
    />
  );
};

View full source

And boom, we don't need to worry about an external service like Cloudinary; NextJS covers all our images optimisation needs.

Deployment

There are a few other components you can explore, like the nav, but we now have a decently versatile page builder.

You can deploy this app to Vercel using the template, and create your own Sanity data lake (the free tier is pretty generous).

You'll want to configure incremental static regeneration to ensure published changes to CMS data are automatically pushed to the main site (see this file - be aware that if you update the schema you'll also need to update the logic that handles that revalidation). This allows you to trigger re-validations on only data which has changed, rather than rebuilding the entire app.

Wrapping Up

Again, you can view the full source code here, which is built with minimal Bootstrap components. Since the CMS is headless, you can style the frontend however you need, or switch to another component library like Material UI - whatever you want really. This makes the template easily adaptable to different clients, you can restyle the app to a brand and grant your client access to Sanity Studio for a minimal maintenance burden. Take a look at this template in action on a full project here.

Type Safe Tailwind and SCSS Modules

TimJ — Fri, 09 Jun 2023 14:00:00 +0000

Applying classes directly to a React component provides no type safety by default. This can lead to errors, unexpectedly missing styles, and a lesser development experience without intellisense. In this blog, I'll be achieving type safety for both Tailwind and SCSS (Sass) Modules.

The Development Experience

You can find the minimal repo with this config here.

Tailwind CSS

Instead of using a class name directly, this works by using a custom utility function. For example:

import cn from "../styles/cssUtils";
...
<div className={cn("container p-5", { "text-lg": true })}>

This works by generating CSS class names for any Tailwind or global classes from the compiled CSS, and generating a union type in cssClasses.d.ts. This is automatically generated during development (npm run dev). Note that unused Tailwind classes are purged and excluded from the type definition, so when adding a new class your IDE will complain momentarily until the file is saved and types are re-generated.

SCSS Modules

To use scoped SCSS modules with type safety, separate ./...module.scss.d.ts files are generated in the directory of it's parent component. This can be used with the cnScoped function, for example:

import { cnScoped } from "../styles/cssUtils";
import styles from "./component.module.scss";
...
<div className={cnScoped(styles)(styles._component, "container p-5", {
  "text-lg": true,
})}>
...

Some things to note:

Classes in SCSS modules are named with a _ prefix and are lowerCamelCase.
Using the styles import is required for the module to be compiled and avoid name collisions, and gives intellisense.
The ClassNames type provides cnScoped with a union of all class names in that SCSS module, so that it knows what valid classes are in scope. Note the extra () since the function needs to by curried.

How it Works

Let's go into detail on how to set things up and how the magic happens.

Generating Types

First we need to generate types. For Tailwind, we can do this using postcss-ts-classnames, which essentially creates a big union type of all the classes it finds in the bundled app. Importantly, this happens after unused classes are purged, so we don't get the entire list of possible Tailwind classes. This is ideal for performance reasons, but does mean there is a small lag between a class being used in code and the generated types being updated.

Update your vite.config.ts to include this config (postCssTsClassnames is the interesting part):

import postCssTsClassnames from 'postcss-ts-classnames';

...

css: {
  postcss: {
    plugins: [
      tailwind,
      autoprefixer,
      postCssTsClassnames({
        dest: 'src/styles/cssClasses.d.ts',
        // Set isModule if you want to import ClassNames from another file
        isModule: true,
        exportAsDefault: true, // to use in combination with isModule
      }),
    ],
  },
},

Given the classes:

<div className="container p-5 text-teal-300">

It generates the file styles/cssClasses.d.ts:

// This file is auto-generated with postcss-ts-classnames.

export type ClassNames = "container" | "p-5" | "text-teal-300";

export default ClassNames;

To generate types for SCSS modules, we use vite-plugin-sass-dts. We simply need to add this to our list of Vite plugins:

plugins: [react(), sassDts()],

Given a SCSS module MyTypeSafeComponent.module.scss:

._myClass {
  color: red;
}

It generates the file MyTypeSafeComponent.module.scss.d.ts:

declare const classNames: {
  readonly _myClass: "_myClass";
};
export = classNames;

One more thing - we need to ignore the auto generated files to stop Vite getting stuck in a cycle of generating the types, noticing that the files storing these types has changes, then generating the types again, and again... We can do this by ignoring these patterns in the vite.config.ts:

server: {
  watch: {
    ignored: ['**/cssClasses.d.ts', '**/*module.scss.d.ts'],
  },
},

Using the Types

To use the global Tailwind types from styles/cssClasses.d.ts, I've leveraged a lot of work from this post, so credit goes there for a lot of the complex TypeScript wizardry that makes things work. In essence, it builds upon the classnames (or clsx) to provide a helper function that gives us with the type safety we're after. This cleverness means we get type checking that works with whitespace, multiple classes (e.g., "container p-5")and arbitrary values (e.g., "border-[5px]"). The input "container p-5 invalid-class" provides the nifty error message:

'invalid-class' is not a valid Tailwind or scoped class

The end result is we get this:

<div
  className={cn(
    // Multiple classes can be a separate param, or within the same string
    "container p-5",
    // Can also use a condition
    { "text-teal-300": true }
  )}
>
  Type Safe Tailwind!
</div>

I've adapted Kimmo's code to work with scoped SCSS modules, all within the same function. Importantly, our Tailwind classes file will be used globally, while the SCSS modules need to be scoped to specific components. There are a few steps to make this happen:

We need to exclude the SCSS classes from the global set of types. We only want to allow classes that are explicitly within scope of a SCSS module. My solution to this is to prefix these SCSS classes with an underscore _, so they can be differentiated from Tailwind types. Optionally, you can also enforce this convention with this Stylelint rule:

  "selector-class-pattern": [
    "^_[a-z][a-zA-Z0-9]+$",
    {
      message:
        "Expected class name to be prefixed with '_' and be lowerCamelCase",
    },
  ]

Which we can then override for the styles directory so we can have some global SCSS too styles/.stylelintrc.cjs:

  module.exports = {
    extends: "../../.stylelintrc.cjs",
    rules: {
      "selector-class-pattern": [
        "^([a-z][a-z0-9]*)(-[a-z0-9]+)*$",
        {
          message: "Expected class name to be kebab-case",
        },
      ],
    },
  };

We need a way to specify the generated types from our SCSS module. Unfortunately (at least to my understanding...), TypeScript can't mix inferred and explicit types, so we need to curry the function, then we can allow those types.

In action, this looks like:

import { cnScoped } from "../styles/cssUtils";
import styles from "./MyTypeSafeComponent.module.scss";

const MyTypeSafeComponent: React.FC = () => (
  <div
    className={cnScoped(styles)(
      styles._myClass,
      // Can be mixed with Tailwind classes
      "container p-5"
    )}
  >
    Type Safe SCSS Modules!
  </div>
);

styles has intellisense and is fully scoped to that component. TypeScript won't let us use an invalid class, a class from an out-of-scope SCSS module, and will work if two classes in different SCSS modules have a name collision. 🚀

Gotchas

Due to a limitation with how TypeScript infers template literals, if a class exists which is a prefix, it will break other classes that use that prefix. For example: flex-col will be marked as invalid because flex is a class. As a workaround, you can pass these classes as separate parameters:

  cn("flex p-5", "flex-col", "flex-wrap");

There are some cases when the Vite dev server is running, but you don't want to regenerate types. One example is when using Storybook. A workaround is to use an environment variable to disable the type generation:

  const enableCssTypeGen = !(process.env.DISABLE_CSS_TYPE_GEN === "true");

Validating Dependent Fields with zod and react-hook-form

TimJ — Sat, 03 Jun 2023 09:06:24 +0000

When building forms, there are complex cases where the validation of one field may depend on the state of another. In this post, I'll implement an example of one such scenario using zod, react-hook-form and Material UI.

Consider the case where a user is providing contact information, and they have several options (email or phone number). Then they need to pick their preferred contact method. We want to validate that the user has entered the contact details for the preferred method they chose, and have other contact details be optional. We need a way to check the validity of the email or phone fields conditional on the chosen preferred contact method.

This post is the second in a series on building forms with React, you can read the previous post here.

Creating the Autocomplete Field

First, let's create the input field component using Material UI. This part will be dealing with integrating an MUI component with react-hook-form, so if you're less interested that and want to skip to the dependent validation logic, jump to # Updating the Schema with Dependent Fields.

To do this, we'll be using Autocomplete, which will give us a dropdown with a list of items we can pick. It also has some extra built-in functionality over a basic select element, that gives us the ability to type and filter for items in the list, and clear the input once selected.

At it's most basic, we can use the component like this:



<Autocomplete
  options={["Email", "Phone"]}
  sx={{ width: 245 }}
  renderInput={(params) => (
    <TextField {...params} required label={"Preferred Contact Method"} />
  )}
/>

Autocomplete acts as wrapper around the base TextField, where we specify the set of possible options. If you've read the previous tutorial, you'll know what's coming next; we need to control the input using react-hook-form and update our zod schema for validation.

Pull out the set of options into a constant, since we'll be using it in a few places:



const contactMethods = ["Email", "Phone"] as const;

Update the zod schema (you can find the code from the previous tutorial on Stackblitz) to include our new field, using a zod enum:



const formSchema = z.object({
  phone: looseOptional(mobilePhoneNumberSchema),
  email: z
    .string()
    .nonempty("Please specify an email")
    .email("Please specify a valid email"),
  preferredContactMethod: z.enum(contactMethods),
});

Finally, add the Autocomplete component to a new react-hook-from Controller within the form (again, referring to code from the previous tutorial):



<Controller
  name="preferredContactMethod"
  control={control}
  render={({
    field: { value, onChange, onBlur, ref },
    fieldState: { error },
  }) => (
    <FormControl>
      <Autocomplete
        onChange={(
          _event: unknown,
          item: (typeof contactMethods)[number] | null
        ) => {
          onChange(item);
        }}
        value={value ?? null}
        options={contactMethods}
        sx={{ width: 245 }}
        renderInput={(params) => (
          <TextField
            {...params}
            required
            error={Boolean(error)}
            onBlur={onBlur}
            inputRef={ref}
            label={"Preferred Contact Method"}
          />
        )}
      />
      <FormHelperText
        sx={{
          color: "error.main",
        }}
      >
        {error?.message ?? ""}
      </FormHelperText>
    </FormControl>
  )}
/>

There are a few nuances here, let's break things down:

We're passing the value and onChange to the Autocomplete component. We can't use the onChange directly. We don't care about the event of the callback, only the item, and unfortunately MUI doesn't infer the types for us. Using TypeScript, we extract the union type from our array of contactMethods via typeof contactMethods[number], but we also need to include null (more on that later). Then we can pass that into the onChange from react-hook-form's Controller in the callback.
A few props react-hook-form uses to control the form need to be passed to the TextField itself, namely: error, onBlur and ref. This allows react-hook-form to put the field in an error state, trigger revalidation on blur, and focus the input respectively.
Like other fields, we use MUI's FormControl and FormHelperText to render the error message.

Since we're treating this as a required field, we need to update the validation message from zod (by default it is just "Required"), Since we aren't dealing with validations on a zod type (like .nonempty()), there are a few possible errors, so we need to be explicit by defining a required_error:



const formSchema = z.object({
  phone: looseOptional(mobilePhoneNumberSchema),
  email: z
    .string()
    .nonempty("Please specify an email")
    .email("Please specify a valid email"),
  preferredContactMethod: z.enum(contactMethods, {
    required_error: "Please select a contact method",
  }),
});

Nice, but you might be wondering... why did we specify null as a possible type of the item that's being passed to onChange? Try selecting a value, then hit the X on the right of the input to clear the selection, then loose focus of the field (remember we specified the revalidate mode of onBlur in the previous tutorial). You'll see:

Expected 'Email' | 'Phone', received null

which is not exactly user-friendly. That's because MUI sets the input to null when clearing the input, so from zod's perspective, the value is still defined. Thankfully, zod catches this as an invalid_type_error, so we just need to update our schema (unfortunately with a bit of duplication):



preferredContactMethod: z.enum(contactMethods, {
  required_error: 'Please select a contact method',
  invalid_type_error: 'Please select a contact method',
}),

You'll also notice an error being logged to the console. That's because MUI interprets a value being undefined as indicating that the component is uncontrolled. But then when the value changes to one of the options, MUI then needs to treat it as controlled, and this can be problematic (here's why). To get around this, we can specify the default value of the component within our useForm hook as null, not undefined:



defaultValues: {
  email: '',
  phone: '',
  preferredContactMethod: null,
},

An aside: the fact that the default/cleared value is null means that if you wanted to make this field optional, .optional() on the schema won't cover you (since that just checks if it is undefined). To solve this, you can preprocess the value to convert null to undefined. The helper function looseOptional we built in the previous tutorial does precisely that.

Updating the Schema with Dependent Fields

Nice, we have our Autocomplete field working, now we want to validate that if the user selects their preferred contact method as "Email", that they actually specify an email (ditto for "Phone").

Something you'll notice is that the validation of each field within the schema is independent of other fields in the schema. We need something else to make that validation happen... superRefine to the rescue!

superRefine allows us to apply validation on the overall z.object(), and gives us the current value of the object, and context that we can use to imperatively "inject" errors into specific fields which react-hook-form can then interpret.

First, let's make both email and phone optional by default, since they'll be required conditionally on preferredContactMethod:



const formSchema = z.object({
  phone: looseOptional(mobilePhoneNumberSchema),
  email: looseOptional(
    z
      .string()
      .nonempty("Please specify an email")
      .email("Please specify a valid email")
  ),
  preferredContactMethod: z.enum(contactMethods, {
    required_error: "Please select a contact method",
    invalid_type_error: "Please select a contact method",
  }),
});

Then we can add the superRefine to the mix:



const formSchema = z.object({
  ...
  }),
})
.superRefine((values, context) => {
  if (
    values.preferredContactMethod === "Email" && !values.email
  ) {
    context.addIssue({
      code: z.ZodIssueCode.custom,
      message: "Please specify an email",
      path: ["email"],
    });
  } else if (
    values.preferredContactMethod === "Phone" && !values.phone
  ) {
    context.addIssue({
      code: z.ZodIssueCode.custom,
      message: "Please specify a phone number",
      path: ["phone"],
    });
  }
});

Try selecting an option, then hit submit. 🤯 context.addIssue allows us to add an error to whatever path we want (be aware that path is only stringly typed), using z.ZodIssueCode.custom since we aren't using any of zod's built-in errors (aka issues).

Triggering Validation Conditionally

Cool, but you may have noticed that the message only updates when hitting the submit button. That's because react-hook-from doesn't know to re-render the email or phone fields when preferredContactMethod changes. We can leverage two things from react-hook-form:

watch the preferredContactMethod for changes.
trigger validation of email and phone.

We can capture this logic as follows:



const { control, handleSubmit, watch, trigger } = useForm<FormFields>({
  ...
});

useEffect(() => {
  const subscription = watch((_value, { name }) => {
    if (name === 'preferredContactMethod') {
      void trigger(['phone', 'email']);
    }
  });

  // Cleanup the subscription on unmount.
  return () => subscription.unsubscribe();
}, [watch, trigger]);

Now the user get immediate feedback based on their selection.

Marking Fields as Required Conditionally

We also want to set the email or phone fields as required conditional on the selected preferredContactMethod. Sure, this is captured by the schema, but this isn't visible to the underlying MUI components.

We could use watch to achieve this as well, but we can optimise our re-renders using getValues:



const { control, handleSubmit, watch, trigger, getValues } =
  useForm<FormFields>({

...

<TextField
  name="phone"
  ...
  required={getValues('preferredContactMethod') === 'Phone'}
/>

and the equivalent for email.

And that's it, we now have a polished UX to conditionally validate different fields. 🚀

You can find the complete source code and an interactive demo on Stackblitz.

Gotchas

If you're using superRefine in a larger form, where there are other unrelated fields to those you want to conditionally validate, you might notice some interesting behaviour. If those unrelated fields are invalid, the logic you defined in superRefine might not trigger, at least until those unrelated fields are made valid. That's because zod doesn't run superRefine until the validation within the z.object() passes, which is intentional, but can lead to an unexpected UX. A workaround is to defined those unrelated fields in a separate z.object(), then do an intersection with the other z.object() with the superRefine to create the overall schema. Props to this GitHub issue for identifying that solution.

An Aside on Discriminated Unions

You might have noticed a drawback of using superRefine in this scenario:

We have to loosen fields in our schema (via looseOptional), then apply conditional logic imperatively. This isn't explicitly defined in the schema itself.
We don't get good type information for this conditional logic. If the chosen contact method is set to Email when the form is submitted, we know that the email field must be defined, and the phone field isn't relevant. We need to write some additional logic when we submit the form to handle this. It seems like our type system isn't being fully leveraged in this case.

Introducing discriminated unions. We can rewrite the schema as follows:



const formSchema = z.discriminatedUnion(
  'preferredContactMethod',
  [
    z.object({
      preferredContactMethod: z.literal('Email'),
      email: z
        .string()
        .nonempty('Please specify an email')
        .email('Please specify a valid email'),
    }),
    z.object({
      preferredContactMethod: z.literal('Phone'),
      phone: mobilePhoneNumberSchema,
    }),
  ]
);

Now we're taking a cleaner, more declarative approach. This also feeds into the types inferred by TypeScript:



type FormFields = {
    preferredContactMethod: "Email";
    email: string;
} | {
    preferredContactMethod: "Phone";
    phone: string;
}

This is great, but at the time of writing, the author of zod is considering deprecating discriminatedUnions in favour of a new API. You can read more about that here.

discriminatedUnion also is somewhat constrained, where superRefine is far more general. Consider a form with fields for start and end dates, where the start date must be before the end date. A discriminatedUnion requires a specific key to determine which schema to use, which isn't possible here, and we must resort to a more imperative superRefine solution.

For those reasons, I wouldn't necessarily recommend using a discriminatedUnion over a superRefine for form validation, but it certainly has potential. I'll be keeping an eye out for some future API from zod (or some other runtime validation library) to fill this niche.

Building Forms with zod and react-hook-form

TimJ — Mon, 29 May 2023 07:27:51 +0000

Creating forms that elegantly handle validation in an accessible, maintainable and extendable way is a challenge. Using zod and react-hook-form we can take a declarative approach that decouples our form, validation and component logic.

We'll be using the following libraries:

zod: Runtime validation allowing us to declare schemas that parse data users input and generates a validation message.
react-hook-form: Gives us a hook to control our form and trigger validation.
Material UI: Component library to style our form input fields.

It should be noted that apart from react-hook-form, these libraries are interchangeable. For example, you could use io-ts instead of zod to define your form schemas, or Bootstrap instead of Material UI.

Rendering a Simple Field

Let's start by creating a simple uncontrolled field for the user to input their email.

<form noValidate>
  <TextField
    name="email"
    label="Email"
    required
    placeholder="example@mail.com"
  />
</form>

A few things to note:

label="Email" defines the visual label on the MUI (Material UI) component, while name="email" is the native HTML name attribute which allows the browser to make suggestions among other things (so you can quickly enter the email you've used on other sites). This may not be desirable in some cases, so you can choose to omit the name prop or add autoComplete="off" to the form element.
We use noValidate on the form to disable native HTML validation. We'll be using our own custom zod codec to define our own flexible validation rules to and have a consistent UX across different browsers.
We haven't specified an onChange or value prop, so the field is currently uncontrolled. We'll be using react-hook-form to manage this for us.
required adds an HTML required attribute which has accessibility properties, and adds a * to the label.

Controlling the Form

Let's introduce react-hook-form to control this input. The core of this library is the useForm hook, lets add that to our form:

const { control, handleSubmit } = useForm({
  defaultValues: {
    email: "",
  },
});

At the moment, we only have a single field so we're just saying that our email input field is empty by default. You'll also notice we don't have anything describing the 'shape' of our form, or any type safety for the data our form contains - keep that in mind for later.

We now have a form control, which allows us to do a lot of magic like watch the data a user inputs into a field, handle validation, and much more. But we need to tell this control what the email input component is. To do this, we wrap the TextField in a Controller like so:

<Controller
  name="email"
  control={control}
  render={({
    field: { value, onChange, onBlur, ref },
    fieldState: { error },
  }) => (
    <TextField
      name="email"
      label="Email"
      placeholder="example@mail.com"
      required
      inputRef={ref}
      value={value}
      onChange={onChange}
      onBlur={onBlur}
      error={Boolean(error)}
    />
  )}
/>

This does a few things:

name="email" on the Controller tells our form controller (control={control}) which field this is. Again, this is different to the name="email" on TextField which is used by the browser for suggestions, etc.
render passes a few props into the MUI TextField:
- value and onChange so that the input can be managed by react-hook-form.
- ref so that the controller can move the user's focus to the input field (e.g., when trying to submit the form and the field is in an invalid state).
- error just gives the MUI component a red outline to make it visually clear when the field is invalid.
- onBlur so that the controller can trigger events (such as validation) when the user is no longer focusing the input.

Note that react-hook-form can also register fields instead. Since we're using a component library, we need to use a Controller, but register will work if you're using a custom HTML input.

Let's also add some logic to submit our form:

A button within form:

  <Button type="submit">Submit</Button>

A function to run on submit (this could be submitting form data to an API, etc.):

  const onSubmit = (data) => console.log(data);

Then hook it up to our form with the prop:

  onSubmit={handleSubmit(onSubmit)}

You should now be able to hit the button and see a JSON object with your inputted email logged to the console. But we have a few problems:

The email is required, but we can still submit our form without specifying it.
We can enter an email in an invalid format, and our form will still accept it.
We don't have any way to display messages to the user when these validation rules fail.
As mentioned earlier, we still don't have good type safety.

Creating a Schema

First, let's make the email field required. To do this, we're going create a zod schema. While this is a relatively simple example, a library like zod allows us to:

Define a set of validation rules and a dynamic message we can display to the user depending on any violated rule.
Allows us to infer TypeScript definitions from that schema.
transform or coerce data inputted by the user. Maybe we need to convert an unknown something to a number, or strip whitespace. Importantly, this 'parsing' logic is tied to the validation logic and happens at the boundaries of our application.
More generally, gives us runtime type checking, so we can make sure the raw data inputted by the user is in a form that our application can consume (why is this important? Read this).

We're going to start with:

const formSchema = z.object({
  email: z.string().nonempty(),
});
type FormFields = z.infer<typeof formSchema>;

then pass it to the useForm hook using the zodResolver from @hookform/resolvers:

const { control, handleSubmit } = useForm<FormFields>({
  mode: "onBlur",
  reValidateMode: "onBlur",
  resolver: zodResolver(formSchema),
  defaultValues: {
    email: "",
  },
});

Boom. You should be able to hit submit without specifying an email, then the outline will turn red and be focused. We don't disable the submit button if the form is in an invalid state. This allows the user to more easily identify what in the form is invalid (you can imagine how important this is in a much larger form than this). You may want to render the button differently, but it should still be interactive. Let's break down what's happening here:

We define that the email field is a string() that is nonempty() using zod. Fields in zod are required by default. The nice thing about zod is that by default it strips any unexpected keys that aren't defined in schema, which makes your application more secure (read more).
We infer the TypeScript type FormFields and pass it to the useForm type param, so now the output data is properly typed and any Controller we define.
Set the validation mode to onBlur. This is ideal for accessibility, since the user validation status doesn't constantly change as the user types, but they don't need to submit before knowing whether that field is valid or not. We also set reValidateMode so that the behaviour is consistent after the first submit.

It's worth noting that react-hook-form has it's own built-in rules, but these don't give us anywhere near the flexibility of zod.

Displaying a Validation Error

Next, let's improve this by rendering out the validation message to the user. Update the render prop within the Controller:

render={({
  field: { value, onChange, onBlur, ref },
  fieldState: { error },
}) => (
  <FormControl>
    <TextField
      name="email"
      label="Email"
      placeholder="example@mail.com"
      required
      inputRef={ref}
      value={value}
      onChange={onChange}
      onBlur={onBlur}
      error={Boolean(error)}
    />
    <FormHelperText
      sx={{
        color: 'error.main',
      }}
    >
      {error?.message ?? ''}
    </FormHelperText>
  </FormControl>
)}

We're using the MUI FormControl and FormHelperText to associate an error message with the input field, if one exists.

Now we can see an error, but not one that is particularly readable:

String must contain at least 1 character(s)

That's because we're using the built in zod error reporter. We can define our
own message instead:

const formSchema = z.object({
  email: z.string().nonempty("Please specify an email"),
});

However, we still allow an invalid email. Thankfully, zod has a built in
email() schema:

const formSchema = z.object({
  email: z
    .string()
    .nonempty("Please specify an email")
    .email("Please specify a valid email"),
});

Now we have a dynamic error message to help the user identify what they got wrong.

Adding Another Field

Let's extend our form with an optional mobile phone number. This has some implications to consider:

We need to make sure the input only contains digits. But a user might try to enter the number in different formats (0400-000-000 or 0400 000 000).
It must be exactly 10 digits long.
It must start with "04".

Let's translate that into schema:

const mobilePhoneNumberSchema = z
  .string()
  // Remove all non-digit characters.
  .transform((value) => value.replace(/\D/gu, ""))
  // Must be 10 digits.
  .refine((value) => value.length === 10, "Please specify 10 digits")
  // Mobile, Cellular, and Satellite services use the code 04.
  .refine(
    (value) => value.startsWith("04"),
    "Mobile numbers must start with '04'"
  );

There are two new parts to this schema:

transform allows us to manipulate the raw value inputted by the user.
Instead of using a built-in validation rule like email, we define our own custom checks with refine.

Now we need to add it to the form schema:

const formSchema = z.object({
  phone: mobilePhoneNumberSchema,
  ...

set the default in the useForm hook:

    defaultValues: {
      phone: '',
      ...

and add the input field within the form:

<form noValidate onSubmit={handleSubmit(onSubmit)}>
  <Controller
    name="phone"
    control={control}
    render={({
      field: { value, onChange, onBlur, ref },
      fieldState: { error },
    }) => (
      <FormControl>
        <TextField
          name="phone"
          label="Phone"
          placeholder="0400-000-000"
          inputRef={ref}
          value={value}
          onChange={onChange}
          onBlur={onBlur}
          error={Boolean(error)}
        />
        <FormHelperText
          sx={{
            color: 'error.main',
          }}
        >
          {error?.message ?? ''}
        </FormHelperText>
      </FormControl>
    )}
  />
  ...

One last thing - we want to make the field optional. We could update some logic in our reusable mobilePhoneNumberSchema, but we might want to use that in other parts of our app where it is required. Instead, let's try adding .optional() to mobilePhoneNumberSchema in the formSchema.

Looks good right? Well not quite. What happens if we enter something, then delete it? It still says:

Please specify 10 digits

So we aren't quite there. This is because .optional() actually only checks if the value is undefined, and once the field is dirty, the value instead becomes an empty string. There are a few other cases where this can happen, such as an MUI select component being null. Here is a helper that will preprocess (similar to transform, but happens before parsing) empty strings and nulls to undefined to make the optional behaviour work as expected:

const looseOptional = <T extends z.ZodTypeAny>(schema: T) =>
  z.preprocess(
    (value: unknown) =>
      value === null || (typeof value === "string" && value === "")
        ? undefined
        : value,
    schema.optional()
  );

Now we can wrap the mobilePhoneNumberSchema with that utility and get the behaviour we expect:

const formSchema = z.object({
  phone: looseOptional(mobilePhoneNumberSchema),
  ...

Some Extra Gotchas

Make sure you only specify required on the input component when it is also required in schema.
You may have multiple forms or even nested forms in complex scenarios, in which case a button with type="submit" might get in your way and trigger submit on multiple forms (very annoying). This is because native HTML is once again getting in our way, you can override it by changing the form onSubmit:

  onSubmit={(event) => {
    // Prevent the event from triggering other active forms.
    event.preventDefault();
    event.stopPropagation();

    void handleSubmit(onSubmit)(event);
  }}

If you need to coerce a value (e.g., a Date via MUI date picker), you can use z.coerce.date() in addition to other primitives respectively. However, you may want a custom validation message in some cases, in which case you'll need to use an error map instead:

  z.date({
    errorMap: (issue, ctx) =>
      issue.code === z.ZodIssueCode.invalid_date
        ? { message: "Please specify a date" }
        : { message: ctx.defaultError },
    coerce: true,
  });

Wrapping Up

Using these three libraries, we are able to decouple our form, validation, and component logic, meaning we can easily define reusable schemas, or swap to a completely different component library with ease. We also get the safety of runtime type checking, while having accessible user-friendly forms with helpful validation messages.

You can find the source code for the example on Stackblitz.

Git Techniques to Undo your Mistakes

TimJ — Sat, 23 Apr 2022 02:48:16 +0000

Oops! You just commited a secret API key! Or maybe you want to revert the changes of an earlier commit. Whatever it may be, this blog will highlight some common VCS mistakes and how to Git things fixed.

Note: the vast majority of these tips apply only before you have pushed your changes to a remote repository. Rewriting the history of a remote repo is scary and should be avoided unless you know what you're doing! If you really want to replace a remote with local state, push with the --force flag.

1. Unstage

Say you want to remove something from the staging area without modifying the file itself.

Check what files are currently in the staging area: git diff --name-only --cached
Unstage a specific file: git reset HEAD <file>
Or unstage everything: git reset HEAD

2. Uncommit

Remove your last commit from the history without changing the working tree (your files): git reset HEAD^
Do the same, but keep files in the staging area: git reset --soft HEAD^
Remove the commit and throw away all changes since the previous commit (be careful with this one): git reset --hard HEAD^

3. Revert a Commit

Some commit in the history has become problematic, so create a new "revert commit" to undo changes:

Find the ref of the commit you want to revert: git log
Create a new revert commit: git revert <ref>

Keeps the original commit intact, and is safe to use for commits that have been pushed to a remote repo.

4. Amend a Commit

You made a typo in a commit message, amend it without changing files: git commit --amend -m "New message"
Change the files of a commit without changing the message: git commit --amend --no-edit

5. Discard

You have modified files, and want to throw everything out and go back to a previous commit.

Option A - Stash your Changes (Recommended)

Stash all your current changes (can also be used for a specific file): git stash push
Also stash untracked files for a clean repo: git stash --all
You can restore your stashed changes whenever you want: git stash pop

Option B - Hard Reset (Not Recommended)

Reset your working tree to the state of a commit (changes will be lost): git reset --hard <commit>
Remove untracked files for a clean repo (-x for ignored files as well): git clean -fd
If you need to recover changes, use git reflog show HEAD and reset back to the ref, though I find stash easier to work with.

6. Rebase

The swiss army knife of git. Can basically do steps 2-4 all in one go. Re-write your history by editing, moving and merging commits. Again, make sure to only use this for commits that have yet to be pushed to a remote repo, else you might get some angry coworkers.

Interactively rebase everything that hasn't been pushed to a remote: git rebase -i
Or rebase the last x commits: git rebase -i HEAD~<x>

Interactive rebase reference:

Commands:
p, pick = use commit
r, reword = use commit, but edit the commit message
e, edit = use commit, but stop for amending
s, squash = use commit, but meld into previous commit
f, fixup = like "squash", but discard this commit's log message
x, exec = run command (the rest of the line) using shell
d, drop = remove commit

This is a very powerful tool - I'd recommend doing some further reading.

Bonus - .gitignore

Create a .gitignore to specify certain files that you don't want added to the staging area (importantly, environment variables and API keys). See this list of templates for different projects.

What to do Next

Set some of these commands as an alias so you don't need to remember everything. See my .gitconfig.
If you use VSCode, install some Git related extensions. For example, I like to use Checkpoints to create temporary local WIP commits to save my work as I go. For a complete list, see my recommended VSCode extensions.
Install some CLI tools. For example, I like to use diff-so-fancy for viewing diffs. For a complete list, see my recommended CLI tools.

Feel free to comment with any additional tips!

The Ultimate List of VSCode Extensions

TimJ — Wed, 20 Apr 2022 00:08:25 +0000

VSCode is highly extensible and customizable. Though VSCode is technically a text editor, the extensions in this list will start to turn it into a feature rich IDE.

Getting Started

Install VSCode
Enable settings sync (ctrl-,). Alternatively, use the Settings Sync extension to sync your settings via GitHub gists.

General

GitHub Copilot: Your AI pair programmer. I, for one, welcome our robot overlords. Note that the preview requires you to sign up for a waitlist.
GitHub Codespaces: Cloud-hosted development environments that allows you to access your projects from a browser.
Live Server: Launch a development local Server with live reload feature for static & dynamic pages.
Live Share: Real-time collaborative development.
- Live Share Whiteboard: Adds a real-time collaborative whiteboard to Visual Studio Live Share sessions.
Remote - SSH: Open any folder on a remote machine using SSH.
- Remote - SSH: Editing Configuration Files: Edit SSH configuration files.
Remote - WSL: Open any folder in the Windows Subsystem for Linux (WSL).
Cacher: Code snippet manger via GitHub gists (paid extension).
vscode-spotify: Use Spotify inside vscode (requires a Spotify subscription).
Browse Lite: Embedded browser in VS Code.
Choose A License: Choose a license for your project in VS Code.
EditorConfig: EditorConfig Support for Visual Studio Code.
vscode-database: Support mysql, postgres, SSL, socked - SQL database.
Snyk: Easily find and fix vulnerabilities in both your code and open source dependencies with fast and accurate scans.

Productivity

IntelliCode: AI-assisted IntelliSense.
Path Intellisense: Autocomplete filenames.
Version Lens: Shows the latest version for each package using code lens.
vscode-faker: Generate fake data for name, address, lorem ipsum, commerce and much more.
Bookmarks: Mark lines and jump to them.
Peacock: Subtly change the workspace color of your workspace.
Output Colorizer: Syntax highlighting for log files.
Bracket Pair Colorizer 2: ~~A customizable extension for colorizing matching brackets.~~ Note: this is now a built-in feature of VSCode, add the following to your settings.json:

  "editor.bracketPairColorization.enabled": true,
  "editor.guides.bracketPairs": true,

Image preview: Shows image preview in the gutter and on hover.
vscode-pdf: Display pdf file in VSCode.

Code Editing

Prettier: General purpose code formatter.
Better Comments: Improve your code commenting by annotating with alert, informational, TODOs, and more. I've also configured it to highligh fixme and note.
Error Lens: Improve highlighting of errors, warnings and other language diagnostics. Some people might find this too distracting, but I think the trade-off is worthwhile as it helps me quickly identify errors. Also works with lots of other extensions, linters and suggestions. I configured it to set a short delay before showing the error.
Regex Previewer: Regex matches previewer.
change-case: Quickly change the case (camelCase, CONSTANT_CASE, snake_case, etc) of the current selection or current word.
Multiple cursor case preserve: Preserves case when editing with multiple cursors.
Rewrap: Hard word wrapping for comments and other text at a given column.
Hungry Delete: Delete an entire block of whitespace or tab.
Tab Out: Tab out of quotes, brackets, etc.
Code Spell Checker: Spell check your code.
DotEnv: Support for dotenv file syntax.
Highlight Bad Chars: Highlight bad characters such as No-break space ( ) and the Greek question mark (;) in your source files.

File Managment

File Utils: A convenient way of creating, duplicating, moving, renaming and deleting files and directories.
advanced-new-file: Create new files with a context menu - specify the file type and location. I've replaced my new file shortcut ctrl-n to use this extension.
Scratchpads: Create multiple scratchpad files for doodling while you're coding. I've set this to the shortcut ctrl-alt-n.

Git

GitLens: Supercharge Git within VS Code. Does a whole lot of Git related things - too many to list here.
Git History: View git log, file history, compare branches or commits
Git Graph: View a Git Graph of your repository, and perform Git actions from the graph.
GitHub Pull Requests: Allows you to review and manage GitHub pull requests and issues.
Checkpoints: Checkpoints used in between commits for keeping a local short-term history of work in progress files, like bookmarks in you undo-stack.
gitignore: Lets you pull .gitignore templates quickly and easily.

Diagramming

Draw.io Integration: Integrates Draw.io into VS Code. Lets you use .drawio.png files, which are both directly editable and easily exported. I use the theme atlas.
PlantUML: Rich PlantUML support for Visual Studio Code.

Appearance

There are plenty of themes to choose from and this comes down to personal preference, but this is what I'm currently using:

One Dark Pro: Atom‘s iconic One Dark theme for Visual Studio Code.
Material Icon Theme: Material Design Icons for Visual Studio Code
Material Product Icons: Product Icon Theme with Material Icons for VS Code.

Specialized Extensions

For pretty much any language out there, you can find extensions for syntax highlighting, linting, formatter, and so on. I'll omit most of those sorts of extensions here, and instead focus on some more interesting or unique extensions.

JavaScript, etc.

ESLint: Linting for JavaScript (I know I said no linters, etc. but this is a must-have).
npm: npm support for VS Code.
Add jsdoc comments: Adds simple jsdoc comments for the parameters of a selected function signature.
Wrap Console Log: Wrap to console.log by word or selection.
Import Cost: Display import/require package size in the editor.
Auto Import: Automatically finds, parses and provides code actions and code completion for all available imports.
Glean: The extension provides refactoring tools for your React codebase.
TypeScript Error Translator: TypeScript errors, translated for humans.

HTML

Auto Close Tag: Automatically closes the tag when you type a space after the tag name.
Auto Rename Tag: Renames the tag when you type a space after the tag name.
Icon Fonts: Snippets for popular icon fonts.

CSS

Colorize CSS: Help visualize css colors in files.
CSS Peak: Quickly view the CSS properties of the current element.

AWS

AWS Toolkit: A collection of AWS tools for Visual Studio Code.
AWS Actions: Provides AWS actions in the editor.
AWS CLI Configure: Quickly access the AWS CLI config & credentials files.

Other

Docker: Makes it easy to create, manage, and debug containerized applications.
Remote - Containers: Open any folder or repository inside a Docker container.
Kubernetes: Develop, deploy and debug Kubernetes applications.
json: Json for Visual Studio Code.
XML Tools: XML Formatting, XQuery, and XPath Tools for Visual Studio Code.
YAML: YAML Language Support by Red Hat, with built-in Kubernetes syntax support.

Markdown

For writing blogs like this one. VSCode has pretty good out-of-the-box support for Markdown, but there are a few useful extensions.

Markdown All in One: All you need to write Markdown (keyboard shortcuts, table of contents, auto preview and more).
markdownlint: Markdown linting and style checking for Visual Studio Code. Be sure to fine tune these rules to your liking.

Next Steps

Install tooling for your favorite language/tool - syntax highlighting, intellisense linting, formatting, etc.
Get familiar with the command pallet ctrl-shift-p. You can search for pretty much anything you want to do, extensions included.
Learn and configure your keyboard shorcuts. Anything from the command pallet can be configured as a keyboard shortcut, and you can set contextual shortcuts for specific languages, etc.
VSCode has a built-in snippet manager, but you can download additional snippets for specific languages/tools.
Configure your editor settings. You can see what I'm current using here. Some notable configuration:
- Set a ruler so your lines of code don't get too long:

  "editor.rulers": [80],
  "workbench.colorCustomizations": {
    "editorRuler.foreground": "#491f1f"
  },

Make your cursor smooth:

  "editor.cursorBlinking": "phase",
  "editor.cursorSmoothCaretAnimation": true,

Install a custom font. I use Caskaydia Cove Nerd Font. Turn on ligatures "editor.fontLigatures": true, for multi-character symbols.
Turn on file nesting to group together similar files:

  "explorer.fileNesting.enabled": true,
  "explorer.fileNesting.patterns": {
    "*.ts": "${capture}.js",
    "*.js": "${capture}.js.map, ${capture}.min.js, ${capture}.d.ts",
    "*.jsx": "${capture}.js",
    "*.tsx": "${capture}.ts",
    "tsconfig.json": "tsconfig.*.json",
    "package.json": "package-lock.json, yarn.lock",
    "README.md": "LICENSE.txt",
    ".eslintrc.*": ".eslintignore, .prettierrc.*, .eslintrc-auto-import.json"
  },
  "explorer.fileNesting.expand": false

Format and organize imports on save:

  "editor.formatOnSaveMode": "modifications",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.organizeImports": true
  },

Auto fetch from version control:

  "git.autofetch": true,

Feel free to comment with any extensions or tips I have missed and I'll add them to the list!

Command Line Tools for Productive Developers

TimJ — Sun, 10 Apr 2022 05:28:03 +0000

This guide is a compilation of various command line tools that will improve your productivity in addition to various quality-of-life features.
Note: for any npm packages, make sure to install globally with -g.

Getting Started

Download a Nerd Font and set your favourite terminal to use it. I like Cascaydia Cove Nerd Font the best.
See my guide for setting up a custom prompt and various plugins using oh-my-zsh. This also includes some useful aliases, keybinds and terminals to use for different platforms.

General Productivity

tmux: Terminal multiplexer that gives you tabs, panes and more natively in the shell. With tmux, you can detach terminal sessions so that they continue running in the background, restore sessions, and even reattach them to a different terminal.
- See this blog to get started with tmux.
- See my .tmux.conf.
- Alternatively, you can also use oh-my-tmux along with a bunch of plugins to extend the capabilities of tmux. See my .tmux.conf.local which has my current configuration using this framework. This is what my tmux looks like, with a customized status bar:
bat: Better cat - supports syntax highlighting for a large number of programming and markup languages.
diff-so-fancy: Makes your diffs human readable instead of machine readable. Go here to see usage with Git.
- Can be used with diff, as in this alias:

diffs() {
  diff -u $1 $2 | diff-so-fancy
}

tldr: Better man (manual) pages.
thefuck: Corrects errors in previous console commands.
how2: Finds the simplest way to do something in a unix shell using a natural language query.
direnv: Load and unload environment variables depending on the current directory (for oh-my-zsh users, see this alternative)
asdf: Manage multiple runtime versions with a single CLI tool.
glow: Terminal based markdown reader.

Search

fzf: General-purpose command-line fuzzy finder.
- fzf can be used for tab completion, history search and more.
- If you are using oh-my-zsh, add fzf to your plugins for keybinds and more.
- You can use fzf to search and bat for file previews using this alias:

if [[ -x "$(command -v fzf)" ]] && [[ -x "$(command -v bat)" ]]; then
  alias fp="fzf --preview 'bat --color=always --style=numbers --line-range=:500 {}'"
fi

rg: Better grep - ripgrep is a line-oriented search tool that recursively searches the current directory for a regex pattern.

Directory Navigation & Management

colorls: Colorizes the ls output with color and icons (requires gem).
- Includes many useful flags, such as --gs for Git status, or -t for a tree view:
- I use an alias to replace ls with colorls:

if [ -x "$(command -v colorls)" ]; then
    alias ls="colorls"
    alias la="colorls -al"
fi

exa: Alternative to colorls (use the --icons flag to get icons like colorls).
tree: Visualize directories in a tree-like format (lightweight alternative to colorls with the -t flag).
broot: Like tree, but works better with big directories.
z: Quickly jump between directories based on history (For zsh users, it is easier to install this plugin)

Utilities

vtop: A graphical activity monitor for the command line.
croc: Simple file transfer via CLI.
secman: CLI password manager.
hyperfine: A command-line benchmarking tool.
gping: Ping, but with a graph.
procs: Replacement for ps.
dog: Command-line DNS client.
duf: A better df alternative.

Git

gh: GitHub CLI - view pull requests, issues, and other GitHub concepts in the terminal.
gitui: Git GUI in your terminal.
diff-so-fancy: Makes your diffs human readable instead of machine readable.
- Add the following to your .gitconfig:

[alias]
    dsf = diff --color
[interactive]
    diffFilter = diff-so-fancy --patch
[color]
    ui = true
[color "diff-highlight"]
    oldNormal = red bold
    oldHighlight = red bold 52
    newNormal = green bold
    newHighlight = green bold 22
[color "diff"]
    meta = 11
    frag = magenta bold
    func = 146 bold
    commit = yellow bold
    old = red bold
    new = green bold
    whitespace = red reverse

commitizen: Get prompted to fill out any required commit fields at commit time.

Package Mangers

There are a wide range of different package managers for different environments (e.g., APT for Ubuntu) and languages (e.g., pip for python), but here are some general package managers that are good to have:

Homebrew: MacOS, but also available on Linux.
Chocolatey: Windows.
nix: For Unix systems, functional package manager.
npm: Package manager for node, but good to have.

Specialized Tools

Depending on what technologies you work with day-to-day, these may or may not be relevant:

jq: JSON processor.
httpie: Command-line HTTP client (better curl).
wget: Another command-line HTTP client.
ngrok: Secure URL to a localhost server.
k9s: Manage your Kubernetes clusters in style.

Next Steps

Customize your theme and prompt. See my guide here.
Use oh-my-zsh to install some zsh plugins. I've created a guide for that here. Some notable plugins include:
- Autocomplete
- Autosuggestions
- Syntax highlighting
- .env auto loading
- Clipboard CLI utilities
- web-search for using search engines via CLI
Create some aliases for frequently used commands. See all my aliases in my aliases.zsh. Note that for git aliases, it is best to define them in your .gitconfig.

Feel free to add a comment suggesting any additional CLI tools and I'll add them to the list!

Overhaul your Terminal with Zsh + AutoComplete + More

TimJ — Sat, 02 Apr 2022 05:23:10 +0000

This guide will look at various ways you can improve your productivity by extending the functionality of your terminal, including:

zsh: A powerful shell that extends the feature set of bash.
zsh plugins: Auto-suggestions, completion, syntax highlighting and more.
prompts + themes: Customize a clean prompt that displays contextual information, either using Powerlevel10k or Posh.

We'll go from this:

To this:

Getting Started

Install oh-my-zsh for any Unix based shell or WSL2, which bundles zsh with a set of plugins and themes.
Download a Nerd Font and set your favourite terminal to use it. I like Cascaydia Cove Nerd Font the best.

Zsh Plugins

To enable plugins locate your .zshrc in your $HOME directory, and add to the list of plugins:

plugins=(
  git
  ...
)

Plugins Included with oh-my-zsh

sudo: Easily prefix your current or previous commands with sudo by pressing esc twice.
dotenv: Automatically load your project ENV variables from .env file when you cd into project root directory. By default, it will prompt before loading, but you can turn this off by adding the following to your .zshrc (though be wary of the security implications of this):

export ZSH_DOTENV_PROMPT=false

copypath: Copies the path of given directory or file to the system clipboard.
copyfile: Puts the contents of a file in your system clipboard so you can paste it anywhere.
copybuffer: This plugin binds the ctrl-o keyboard shortcut to a command that copies the text that is currently typed in the command line ($BUFFER) to the system clipboard.
command-not-found: provide suggested packages to be installed if a command cannot be found.
web-search: This plugin adds aliases for searching with Google, Wiki, Bing, YouTube and other popular services.
history: Provides a couple of convenient aliases for using the history command to examine your command line history.
dirhistory: Adds keyboard shortcuts for navigating directory history and hierarchy. Uses alt-arrowkeys by default, so ensure these do not conflict with other shortcuts.
colorize: Syntax-highlight file contents of over 300 supported languages and other text formats.
colored-man-pages: Adds colors to man pages.
magic-enter: This plugin makes your enter key magical, by binding commonly used commands to it. You customize the command it uses, and run specific commands in a Git repo:

MAGIC_ENTER_GIT_COMMAND='git status -sb .'
MAGIC_ENTER_OTHER_COMMAND='ls -la .'

jsontools: Handy command line tools for dealing with json data.

Depending on what other software you use, there are plenty of lightweight plugins that improve autocompletion and provide aliases among other things. I use:

git: Aliases for Git
gh: Completions for GitHub cli
git-auto-fetch: Periodically run git fetch
nvm: Completions for nvm
npm: Completions + aliases for npm
aws: Completions for aws
docker: Completions for docker
docker-compose: Completions + aliases for docker compose
kubectl" Completions + aliases for kubectl
vscode: Aliases for VS Code or VSCodium editor
python: Aliases for python
pip: Automcompletions for pip
tmux: Aliases for tmux

Powerful Plugins

These plugins do not come with oh-my-zsh, so you must clone the repos and place them in ~/ohmyzsh/custom/plugins/ before adding them to the plugins list in the .zshrc.

zsh-autosuggestions: Suggests commands as you type based on history and completions, which can then be selected with →.
- Autosuggestions can either use your history, or tab completion. Set this with the ZSH_AUTOSUGGEST_STRATEGY variable.
- Has some compatability issues where the suggestion is not cleared after certain actions. To fix this, add the following to your .zshrc:

ZSH_AUTOSUGGEST_CLEAR_WIDGETS+=(bracketed-paste up-line-or-search down-line-or-search expand-or-complete accept-line push-line-or-edit)

zsh-syntax-highlighting: Syntax highlighting for the shell zsh.
zsh-autocomplete: Provides completion suggestions below the prompt, in addition to a history menu. This one is powerful, but might take some getting used to. Like with autosuggestions, you can choose whether you want to use normal completions (directories, man, etc.) or history search. I like to have autocomplete for normal completions and autosuggestions for history. If you're like me and don't like the history menu, but want all the other features, you can change the keybinds to use a simple history search in your .zshrc (make sure this is after the plugins have been loaded):

bindkey '\e[A' history-beginning-search-backward
bindkey '\eOA' history-beginning-search-backward
bindkey '\e[B' history-beginning-search-forward
bindkey '\eOB' history-beginning-search-forward
zle -A {.,}history-incremental-search-forward
zle -A {.,}history-incremental-search-backward

Similarly, to use the default tab completion, set the following options:

zstyle ':autocomplete:*' widget-style menu-select
bindkey -M menuselect '\r' accept-line

I also don't like the completions to move the prompt around too much, especially for a multiline prompt. We can change this with:

zstyle ':autocomplete:*' list-lines 7

The plugin also has some issues with the prompt "" showing on some completions and eating inputs. Add this to your .zshrc as a workaround (however this sometimes drops completions entirely, but I still prefer this over loosing inputs):

zstyle ':completion:*' menu select=long

For a full list of config options, go here.

zsh-z: Tool to jump quickly to directories that you have visited frequently.
zsh-direnv: Alternative to dotenv, which also provides the use of a .envrc with utility functions.

To take things further, I recommend checking out this curated list of plugins.

Themes + Custom Prompts

We can improve our prompt to contain additional information, such as execution time, performance metrics, and even things like your current Git branch. Set your theme by adding the following to your .zshrc (set to random until you find something you like):

ZSH_THEME="mytheme"

I like agnoster best:

As nice as our prompt looks, we can take things further.
We have 2 options:

Option A: Powerlevel10k

Powerlevel10k is a highly customizable theme for zsh. It includes some nice features such as an instant prompt while plugins are loading, and a configuration wizard to get you started.

This is what my prompt looks like:

I've modified the configuration a bit to use custom icons for specific directories and cleaned up the git status a bit. See my .p10k.zsh

Option B: oh-my-posh

oh-my-posh:
provides a wide range of themes to choose from, though is missing some features of Powerlevel10k such as instant prompt.

Follow installation instructions and find a theme you like. Some favourites of mine are clean-detailed, blueish, or nu4a.
Add the path to your chosen theme to .zshrc:

eval "$(oh-my-posh --init --shell zsh --config ~/.mytheme.omp.json)"

Other Customization for .zshrc

For reference, see my complete .zshrc

Disable auto zsh updates: zstyle ':omz:update' mode disabled
Print ... while waiting for completions to load (doesn't work with zsh-autocomplete): COMPLETION_WAITING_DOTS="true"
Custom aliases. For oh-my-zsh, it is recommended to put aliases in a different file: ~/.oh-my-zsh/custom/aliases.zsh. Some I like to use for networking things:

alias get-ports="netstat -tulnp | grep LISTEN"
alias get-router="ip route | grep default"
alias get-ip="hostname -I"

You can also create an alias function with parameters. For example, to backup a file:

bak() {
  cp $1{,.bak}
}

We can check that a command exists before setting the alias. For example, we can check docker is installed:

if [ -x "$(command -v docker)" ]; then
    alias dw="watch \"docker ps --format \\\"table {{.Names}}\t{{.Status}}\\\" -a\""
fi

See all my aliases in my aliases.zsh. Note that for git aliases, it is best to define them in your .gitconfig.

Custom keybinds. For example: bindkey '^H' backward-kill-word binds ctrl-bksp to delete by word. Find keycodes here. Those familiar with vim shortcuts can add bindkey -v to their .zshrc. Be wary of conflicts with other keybinds/plugins!
Change the default colors for certain directories by adding the following to my .zshrc (go here for color codes):

zstyle ':completion:*:default' list-colors \
  "ow=30;43"

Alternatively, you can export a complete color scheme from file:

eval "$(dircolors ~/.dircolors)";

Set preferred editor for specific files:

alias -s {cs,ts,html,json,xml,md}=code

Set preferred editior for ssh, for example:

if [[ -n $SSH_CONNECTION ]]; then
  export EDITOR='vim'
else
  export EDITOR='code'
fi

Organize all your environment variables in another file: export $(cat ~/.my_env)
You can automatically install packages, for example you can install nvm:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"  # This loads nvm bash_completion

Next Steps

Install tmux for tabs, panes and more natively in the shell. See oh-my-tmux and my tmux.conf.local.
Install a better terminal. My suggestions:
- Ubuntu: Guake
- Windows: Windows Terminal
- MacOS: iTerm2
Read this blog for some general CLI utilies to boost your productivity further.

DEV Community: TimJ

The Best ESLint Rules for React Projects

Official React Plugin

Rules of Hooks

React Refresh

JSX Ally

Naming Conventions and Filename Rules

TS/JSDoc

Bonus - Arrow Function Styles

Wrapping Up

Creating a Site Builder with NextJS and Sanity CMS

Overview

Defining the Entity Structure

Defining the Schemas

Pages

Rich Text Blocks

Defining the Nav

Building Out the React Frontend

Portable Text

URL Links

File Links

Embedded Files and PDFs

Images

Deployment

Wrapping Up

Type Safe Tailwind and SCSS Modules

The Development Experience

Tailwind CSS

SCSS Modules

How it Works

Generating Types

Using the Types

Gotchas

Further Reading / Resources

Validating Dependent Fields with zod and react-hook-form

Creating the Autocomplete Field

Updating the Schema with Dependent Fields

Triggering Validation Conditionally

Marking Fields as Required Conditionally

Gotchas

An Aside on Discriminated Unions

Further Reading

Building Forms with zod and react-hook-form

Rendering a Simple Field

Controlling the Form

Creating a Schema

Displaying a Validation Error

Adding Another Field

Some Extra Gotchas

Wrapping Up

Further Reading

Git Techniques to Undo your Mistakes

1. Unstage

2. Uncommit

3. Revert a Commit

4. Amend a Commit

5. Discard

Option A - Stash your Changes (Recommended)

Option B - Hard Reset (Not Recommended)

6. Rebase

Bonus - .gitignore

What to do Next

The Ultimate List of VSCode Extensions

Getting Started

General

Productivity

Code Editing

File Managment

Git

Diagramming

Appearance

Specialized Extensions

JavaScript, etc.

HTML

CSS

AWS

Other

Markdown

Next Steps

Command Line Tools for Productive Developers