DEV Community: RealGuillaume

What is Blitz.js & How to Get Started With It

RealGuillaume — Thu, 14 Oct 2021 19:42:34 +0000

As developers, we're always looking for ways to optimize our web apps development process and reduce the tedious repeating of manual work.

From the early days of Ruby on Rails to the takeover by React, we've seen new frameworks and architecture streamline the way we work.

And now, a relatively new fullstack JavaScript framework has come into the picture to address a key pain point that Jamstack developers are facing today. I'm talking about Blitz.js, the "batteries-included" framework. Because nobody misses the good old days when buying a brand new "portable" CD player meant you also had to think about AA batteries.

Here's what we'll explore today:

What is Blitz.js?
Why using Blitz.js instead of Next.js?
How to build a web app with Blitz.js?

Let's dive right into it!

What is Blitz.js?

Blitz.js is a fullstack framework created by Brandon Bayer and built on top of Next.js (which in itself is built on top of React 🤯). It is designed as a monolithic foundation that includes everything from database communication to frontend development. No need for REST/GraphQL.

It utilizes a "zero-API" concept that bypasses the need to write an API layer in the frontend. Instead of fetching the data from your backend, you write queries and mutations, automatically generating the frontend API layer after building the project. External apps can also use this API. It also comes integrated with commonly used developer plugins such as ESLint and Prettier, to name a few.

"But wait, I'm a Jamstack developer. I don't want a monolithic solution. I want freedom."

Well, here comes Blitz, the agnostic monolith. Take the database, for example - Blitz comes out-of-the-box with Prisma 2. However, you're free to switch to another one like Fauna or DynamoDB. The same goes for the configuration; deciding a folder structure, defining routing conventions, selecting a styling library, and adding authorization and authentication are all set up by default, but that doesn't mean you cannot go your own way.

Working with Blitz accelerates development by scaffolding code structure based on models, covering everything from database migrations to frontend forms.

It also takes on a concept introduced by Gatsby called "Recipes". Blitz.js lends a hand to developers by simplifying the integration of third-party dependencies using just a single command.

Blitz web app architecture via "blitzjs.com"

This means that you won't need any other frameworks, tools, or APIs to build a web app. Now, all can be done using Blitz.js alone.

TL;DR

Blitz.js is a fullstack framework built on Next.js that lets you import server code directly into React components.

Here are the key features of Blitz:

Fullstack & Monolithic

You only have one code base to develop and deploy. Everything from the backend to the frontend is done within this framework, and you don't need to assemble multiple layers across the stack to build your app.

APIs not required

You can simply write functions that run on the server and import them directly in your React components in your frontend if needed.

Convention over configuration

Configuration is optional. Everything from authentification to authorization is set up by default.

Why use Blitz.js instead of Next.js?

That's all great, but what exactly makes Blitz.js different from Next.js, and why should I build an app using Blitz instead?

As you know, Blitz.js is built on Next.js so, it can do everything Next.js can, with the addition of extra features bringing more flexibility and fewer headaches :

Blitz.js is a fullstack database-agnostic framework, whereas Next.js requires you to manually set up a database and API to achieve the same result. This makes Blizt.js a more convenient choice while remaining flexible (which is paramount).
The "Zero-API" data layer of Blitz.js creates an effortless and powerful end-to-end data layer by allowing you to import your server code directly into your components. It will then automatically insert API calls to the server code at build time. The model definition can also generate code from Prisma (or another database) migrations up to the frontend page.
Finally, it includes recipes that let you install code and/or packages with one command. A solid addition to the simple npm install.

Tutorial: creating a Blitz.js e-commerce app

Enough of introduction, time to jump in the code and see what Blitz is really capable of.

Prerequisites

Basic knowledge of JavaScript
Snipcart account (free to test forever)
Basic knowledge of Chakra UI

Installing Blitz.js

Let's start with installing the Blitz CLI.

Run: npm install -g blitz --legacy-peer-deps or yarn global add blitz

Then run the following in your terminal to create our Blitz.js app.

blitz new blitzjs-example
cd blitzjs-example
blitz dev

To see our newly created app, head over to http://localhost:3000.

The signup and sign-in are already implemented by the default Blitz.js template. However, in this demo, we'll only be using it for admin rights.

Now here is one part of the 'magic' of Blitz.js. The website's database is already up. To open the management interface, we'll first boot it by running:

blitz prisma studio

If this spits out an error, try:

blitz prisma studio --browser none

To manage our database, simply go to http://localhost:5555.

Scaffolding the products

We'll now define the product in Blitz and ask it to generate the code.

In the command line, enter the following:

blitz generate all product price:float description:string image:string name:string

You can now look at the products folder. It should include:

A components folder containing the product creation form.
A mutations folder containing operations analogic to the "create", "update", and "delete" side of a CRUD API.
A queries folder containing operations analogic to the "read" side of a CRUD API

If we look at the pages/products folder, we can see that the new pages related to the product model operations are named according to their intended routes. Blitz.js will use this nomenclature to create the actual routes.

For this demo, we'll use the default authentication for website admin purposes.

First, let's add the admin database seed by replacing the content of db/seeds.ts with this code:

import db from "./index"
import { SecurePassword } from "blitz"

/*
 * This seed function is executed when you run `blitz db seed`.
 *
 */
const admins = [
  {
    email: "admin@admin.com",
    password: "admin12345",
  },
]

const seed = async () => {
  for (let i = 0; i < admins.length; i++) {
    const admin = admins[i]
    if (admin) {
      const hashedPassword = await SecurePassword.hash(admin.password)
      await db.user.create({
        data: { email: admin.email, hashedPassword, role: "USER" },
        select: { id: true, name: true, email: true, role: true },
      })
    }
  }
}

export default seed

Once saved, run blitz db seed. Then, delete all references to the signup page by deleting app\auth\pages\signup.tsx and removing the following section in app\auth\components\LoginForm.tsx page:

<div style={{ marginTop: "1rem" }}>
Or <Link href={Routes.SignupPage()}>Sign Up</Link>
</div>

In our first recipe, we'll add Chakra UI by using blitz install chakra-ui. Then we'll add the chakra-ui icons using npm install @chakra-ui/icons.

Setting up our layout

We'll now add a menu and a footer that we will later integrate into our layout.

For this, add the file WithMenu.tsx in app/core/components and paste this code in it:

import {Link} from "blitz"
import {
  Box,
  Flex,
  HStack,
  IconButton,
  Button,
  Menu,
  useDisclosure,
  useColorModeValue,
  Stack,
} fom '@chakra-ui/react';
import { useCurrentUser } from "app/core/hooks/useCurrentUser"
import { HamburgerIcon, CloseIcon } from '@chakra-ui/icons';

export interface MenuItem {
  href: string
  label: string
  adminPage: boolean
}

const menuItems: Array<MenuItem> = [
  {label: 'products', href:'/products', adminPage:false}, 
  {label: 'create a product', href:'/products/new', adminPage:true},
  {label: 'add an image', href:'/api/files/upload', adminPage:true}];

  const NavLink = ( props: { menuItem: MenuItem}) => (
    <Link href={props.menuItem.href}>
            <a>{props.menuItem.label}</a>
    </Link>
  );

export default function WithMenu() {
  const currentUser = useCurrentUser()
  const { isOpen, onOpen, onClose } = useDisclosure();

  return (
    <>
      <Box bg={useColorModeValue('gray.100', 'gray.900')} px={4}>
        <Flex w={{md:'80%'}} m={'auto'} h={16} alignItems={'center'} justifyContent={'space-between'}>
          <IconButton
            size={'md'}
            icon={isOpen ? <CloseIcon /> : <HamburgerIcon />}
            aria-label={'Open Menu'}
            display={{ md: 'none' }}
            onClick={isOpen ? onClose : onOpen}
          />
          <HStack spacing={8} alignItems={'center'}>
            <Box><img src="blitzJsExamplelogo.png" alt="Logo" width="70px" /></Box>
            <HStack
              as={'nav'}
              spacing={4}
              display={{ base: 'none', md: 'flex' }}>
              {menuItems.map((link: MenuItem) => {
                if(!link.adminPage || currentUser) {
                  return (
                    <NavLink key={link.label} menuItem={link}></NavLink>
                  )
                }
              }
              )}
            </HStack>
          </HStack>
          <Flex alignItems={'center'}>
          <Button className="header__checkout snipcart-checkout">
                        <svg width="31" height="27" viewBox="0 0 31 27" fill="none" xmlns="<http://www.w3.org/2000/svg>">
                            <path
                                d="M1.10512 0.368718C0.560256 0.368718 0.118164 0.812066 0.118164 1.35848C0.118164 1.9049 0.560256 2.34824 1.10512 2.34824H4.90887L8.30138 18.4009C8.43503 19.0053 8.83085 19.5079 9.32946 19.5041H25.7788C26.3005 19.5118 26.7799 19.0375 26.7799 18.5143C26.7799 17.9911 26.3006 17.5168 25.7788 17.5245H10.1315L9.71003 15.545H27.095C27.5371 15.5412 27.9547 15.2048 28.0511 14.7718L30.354 4.87412C30.4825 4.29933 29.9852 3.67172 29.3979 3.66786H7.21171L6.6771 1.15221C6.58329 0.71276 6.15921 0.368652 5.7107 0.368652L1.10512 0.368718ZM7.623 5.64746H12.7634L13.2569 8.61674H8.25005L7.623 5.64746ZM14.7785 5.64746H20.9881L20.4946 8.61674H15.2719L14.7785 5.64746ZM23.0031 5.64746H28.1537L27.4649 8.61674H22.5097L23.0031 5.64746ZM8.67181 10.5963H13.5862L14.0797 13.5656H9.29919L8.67181 10.5963ZM15.6009 10.5963H20.1656L19.6721 13.5656H16.0944L15.6009 10.5963ZM22.1807 10.5963H27.0023L26.3135 13.5656H21.6872L22.1807 10.5963ZM12.6197 20.164C10.8141 20.164 9.32979 21.6525 9.32979 23.4632C9.32979 25.2739 10.8141 26.7624 12.6197 26.7624C14.4252 26.7624 15.9095 25.2739 15.9095 23.4632C15.9095 21.6525 14.4252 20.164 12.6197 20.164ZM22.4892 20.164C20.6837 20.164 19.1994 21.6525 19.1994 23.4632C19.1994 25.2739 20.6837 26.7624 22.4892 26.7624C24.2948 26.7624 25.7791 25.2739 25.7791 23.4632C25.7791 21.6525 24.2948 20.164 22.4892 20.164ZM12.6197 22.1435C13.3586 22.1435 13.9356 22.7222 13.9356 23.4632C13.9356 24.2042 13.3586 24.7829 12.6197 24.7829C11.8807 24.7829 11.3037 24.2042 11.3037 23.4632C11.3037 22.7222 11.8807 22.1435 12.6197 22.1435ZM22.4892 22.1435C23.2282 22.1435 23.8052 22.7222 23.8052 23.4632C23.8052 24.2042 23.2282 24.7829 22.4892 24.7829C21.7503 24.7829 21.1733 24.2042 21.1733 23.4632C21.1733 22.7222 21.7503 22.1435 22.4892 22.1435Z"
                                fill="#6b7d79" className="header__checkout-fill"></path>
                        </svg>
                    </Button>
          </Flex>
        </Flex>

        {isOpen ? (
          <Box pb={4} display={{ md: 'none' }}>
            <Stack as={'nav'} spacing={4}>
            {menuItems.map((link) => {
              if(!link.adminPage || currentUser) {
                return (
                  <NavLink menuItem={link}  key={link.label} ></NavLink>
                )
              }
            }
              )}
            </Stack>
          </Box>
        ) : null}
      </Box>
    </>
  );
}

Now let's create our footer by adding the file WithFooter.tsx in app/core/components. In this file, add the following lines:

import {
    Box,
    Container,
    Stack,
    Text,
    Link,
    useColorModeValue,
    HStack,
  } from '@chakra-ui/react';

  export default function WithFooter() {
    return (
      <Box mt={'40px'}
        bg={useColorModeValue('gray.50', 'gray.900')}
        color={useColorModeValue('gray.700', 'gray.200')}>
        <Container
        w={{md:'80%'}} m={'auto'}
          as={Stack}
          maxW={'6xl'}
          py={4}
          direction={{ base: 'column', md: 'row' }}
          spacing={4}
          justify={{ base: 'center', md: 'space-between' }}
          align={{ base: 'center', md: 'center' }}>
             <HStack spacing={8} alignItems={'center'}>
             <img src="blitzJsExamplelogo.png" alt="Logo" width="55px" />
          <Stack direction={'row'} spacing={6}>

            <Link href={'/login'}>admin</Link>
          </Stack>
          </HStack>
          <Text>© 2020 BlitzJs example. All rights reserved</Text>
        </Container>
      </Box>
    );
  }

Once our menu and footer components have been created, it's time to integrate them into our layout. To do so, replace the content of Layout.tsx, located in app/core/layouts/, with the following:

import { ReactNode } from "react"
import { Head } from "blitz"
import { Suspense } from "react"
import WithMenu from "app/core/components/WithMenu"
import WithFooter from "app/core/components/WithFooter"
import { Box } from '@chakra-ui/react';

type LayoutProps = {
title?: string
children: ReactNode
}

const Layout = ({ title, children }: LayoutProps) => {
return (
<>
<Head>
<title>{title || "blitzjs-example"}</title>
<link rel="icon" href="/favicon.ico" />
<link rel="preconnect" href="[<https://cdn.snipcart.com>](<https://cdn.snipcart.com/>)"></link>
<link rel="stylesheet" href="[<https://cdn.snipcart.com/themes/v3.2.1/default/snipcart.css>](<https://cdn.snipcart.com/themes/v3.2.1/default/snipcart.css>)" />
<script async src="[<https://cdn.snipcart.com/themes/v3.2.1/default/snipcart.js>](<https://cdn.snipcart.com/themes/v3.2.1/default/snipcart.js>)"></script>
</Head>
<div>
<div hidden id="snipcart" data-api-key="YOUR-API-KEY"></div>
<Suspense fallback="Loading...">
<WithMenu />
<Box w={'80%'} m={'40px auto'}>
{children}
</Box>
<WithFooter />
</Suspense>
</div>
</>
)
}
export default Layout

Make sure to replace the content of the data-api-key attribute with your Snipcart test API key.

Creating the product creation form

To create our product creation form, we'll use our newly installed chakra-ui package. This simple component library will help add a little bit of personality to our form layout page.

Replace the content of app/core/components/Form.tsx with this:

import { ReactNode, PropsWithoutRef } from "react"
import { Form as FinalForm, FormProps as FinalFormProps, } from "react-final-form"
import { z } from "zod"
import { validateZodSchema } from "blitz"
import { Box, ButtonGroup, Button,ThemeProvider, theme  } from "@chakra-ui/react";
export { FORM_ERROR } from "final-form"

export interface FormProps<S extends z.ZodType<any, any>>
  extends Omit<PropsWithoutRef<JSX.IntrinsicElements["form"]>, "onSubmit"> {
  /** All your form fields */
  children?: ReactNode
  /** Text to display in the submit button */
  submitText?: string
  schema?: S
  onSubmit: FinalFormProps<z.infer<S>>["onSubmit"]
  initialValues?: FinalFormProps<z.infer<S>>["initialValues"]
}

export function Form<S extends z.ZodType<any, any>>({
  children,
  submitText,
  schema,
  initialValues,
  onSubmit,
  ...props
}: FormProps<S>) {
  return (
    <ThemeProvider theme={theme}>
    <Box w={500} p={4} m="20px auto"
    borderWidth="1px"
    rounded="lg"
    shadow="1px 1px 3px rgba(0,0,0,0.3)">
    <FinalForm
      initialValues={initialValues}
      validate={validateZodSchema(schema)}
      onSubmit={onSubmit}
      render={({ handleSubmit, submitting, submitError }) => (
        <form onSubmit={handleSubmit} className="form" {...props}>
          {/* Form fields supplied as children are rendered here */}
          {children}

          {submitError && (
            <div role="alert" style={{ color: "red" }}>
              {submitError}
            </div>
          )}

          {submitText && (
            <ButtonGroup spacing={4}>
              <Button
                isLoading={submitting}
                disabled={submitting}
                loadingText="Submitting"
                colorScheme="teal"
                type="submit"
              >
                {submitText}
              </Button>
            </ButtonGroup>
          )}

          <style global jsx>{`
            .form > * + * {
              margin-top: 1rem;
            }
          `}</style>
        </form>
      )}
    />
    </Box>
    </ThemeProvider>
  )
}

export default Form

Now we will customize the product form container.

For this, we'll replace the content of app/pages/products/new.tsx with:

import { Link, useRouter, useMutation, BlitzPage, Routes } from "blitz"
import Layout from "app/core/layouts/Layout"
import createProduct from "app/products/mutations/createProduct"
import { ProductForm, FORM_ERROR } from "app/products/components/ProductForm"

const NewProductPage: BlitzPage = () => {
  const router = useRouter()
  const [createProductMutation] = useMutation(createProduct)

  return (
    <div>

      <ProductForm
        submitText="Create Product"
        onSubmit={async (values) => {
          try {
            const product = await createProductMutation(values)
            router.push(Routes.ShowProductPage({ productId: product.id }))
          } catch (error: any) {
            console.error(error)
            return {
              [FORM_ERROR]: error.toString(),
            }
          }
        }}
      />

    </div>
  )
}

NewProductPage.authenticate = true
NewProductPage.getLayout = (page) => <Layout title={"Create New Product"}>{page}</Layout>

export default NewProductPage

Then, replace the content of the actual form at app/products/components/ProductForm.tsx by:

import { Form, FormProps } from "app/core/components/Form"
import { LabeledTextField } from "app/core/components/LabeledTextField"
import { z } from "zod"
export { FORM_ERROR } from "app/core/components/Form"

export function ProductForm<S extends z.ZodType<any, any>>(props: FormProps<S>) {
  return (
    <Form<S> {...props}>
      <LabeledTextField name="name" label="Name" placeholder="Name" />
      <LabeledTextField name="price" label="Price" placeholder="Price" type="number" />
      <LabeledTextField name="description" label="Description" placeholder="Description" />
      <LabeledTextField name="image" label="Image" placeholder="Image" />
    </Form>
  )
}

Now that the frontend side of the form is done, time to add the backend side, in this case, the createProduct mutation file.

Replace the content of app/products/mutations/createProduct.ts with:

import { resolver } from "blitz"
import db from "db"
import { z } from "zod"

const CreateProduct = z.object({
  name: z.string(),
  price: z.number(),
  description: z.string(),
  image: z.string(),
})

export default resolver.pipe(resolver.zod(CreateProduct), resolver.authorize(), async (input) => {
  const product = await db.product.create({ data: input })
  return product
})

To see the result, run blitz dev and head on to http://localhost:3000/products/new to create a product.

Showing the products in our store

Once your products have been created, we'll add their "card" to the main page

First, add the file SplitScreenProduct.tsx in the app/products/components folder, and paste this code in it:

import {
  Button,
  Flex,
  Heading,
  Stack,
  Text,
  Image,
  useBreakpointValue,
  Box,
} from "@chakra-ui/react"

function ProductImage(props: { imageURL }) {
  return (
    <Flex flex={1} m={"auto"}>
      <Image alt={"Login Image"} objectFit={"contain"} alignItems="center" src={props.imageURL} />
    </Flex>
  )
}

function ProductSummary(props: { product }) {
  return (
    <Flex m={"auto"} flex={1} align={"center"} justify={"center"}>
      <Stack spacing={6} w={"full"} maxW={"lg"}>
        <Heading fontSize={{ base: "3xl", md: "4xl", lg: "5xl" }}>
          <Text color={"black.400"} as={"span"}>
            {props.product.name}
          </Text>{" "}
        </Heading>
        <Text fontSize={{ base: "md", lg: "lg" }} color={"gray.500"}>
          {props.product.description}
        </Text>
        <Stack align="strech" direction={"row"} spacing={4} width={"100%"}>
          <Text fontSize={{ base: "2xl", lg: "3xl" }} color={"black.400"} as={"span"}>
            {props.product.price} {"$"}
          </Text>
          <Button
            className="snipcart-add-item"
            data-item-id={props.product.id}
            data-item-price={props.product.price}
            data-item-url={props.product.url}
            data-item-description={props.product.description}
            data-item-image={props.product.image}
            data-item-name={props.product.name}
            fontSize={{ base: "1xl", lg: "2xl" }}
            flex={1}
            w={"80%"}
            h={"auto"}
            bg={"blue.400"}
            color={"white"}
            _hover={{
              bg: "blue.500",
            }}
          >
            Add to cart
          </Button>
        </Stack>
      </Stack>
    </Flex>
  )
}

export function SplitScreenProduct(props: { product; position }) {
  return (
    <Box flex="1">
      <Stack display={{ base: "none", md: "flex" }} direction={{ md: "row" }}>
        {props.position == "left" && <ProductImage imageURL={props.product.image} />}
        <ProductSummary product={props.product} />
        {props.position == "right" && <ProductImage imageURL={props.product.image} />}
      </Stack>
      <Stack display={{ md: "none" }} direction={{ base: "column" }}>
        <ProductImage imageURL={props.product.image} />
        <ProductSummary product={props.product} />
      </Stack>
    </Box>
  )
}

Now we'll integrate that component into our main page while alternating the position of the text and picture. We will also bring our product API address into the picture. This will allow Snipcart to go to this address to verify the integrity of the products in any carts

Replace the content of app\\pages\\index.tsx with:

import { BlitzPage, useQuery } from "blitz"
import Layout from "app/core/layouts/Layout"
import getProducts from "app/products/queries/getProducts"
import { SplitScreenProduct } from "app/products/components/SplitScreenProduct"
import { Stack } from "@chakra-ui/react"
export const ProductsList = ({ jsonProductApi }) => {
  const [products] = useQuery(getProducts, null)
  const productsWithJsonUrl = products.map((product) => {
    return {
      ...product,
      url: jsonProductApi,
    }
  })

  return (
    <Stack spacing={"50px"}>
      {productsWithJsonUrl.map((product, index) => (
        <SplitScreenProduct
          key={product.id}
          position={index % 2 == 0 ? "right" : "left"}
          product={product}
        />
      ))}
    </Stack>
  )
}

const Home: BlitzPage<any> = ({ jsonProductApi }) => {
  return (
    <div className="container">
      <main>
        <ProductsList jsonProductApi={jsonProductApi} />
      </main>
    </div>
  )
}

Home.suppressFirstRenderFlicker = true
Home.getLayout = (page) => <Layout title="Home">{page}</Layout>

export default Home

export async function getServerSideProps(context) {
  const jsonProductApi = `${context.req.headers.host}/api/products`
  return {
    props: { jsonProductApi }, // will be passed to the page component as props
  }
}

The default getProduct query includes pagination, which we do not need in our single-page demo.

To fix that, replace the content of app\\products\\queries\\getProducts.ts with:

import { paginate, resolver } from "blitz"
import db, { Prisma } from "db"

export default resolver.pipe(
  resolver.authorize(),
  async () =>{
    const products = await db.product.findMany()
    return products;
  }
)

Uploading images with Blitz.js

Unfortunately, Blitz.js doesn't have an easy solution for file uploading yet, so we will have to build our own basic file uploading API. We'll also need to install the formidable package by running npm install formidable.

In app/api, create a files folder and subsequently create a upload.ts file with this content:

import { BlitzApiHandler, BlitzApiRequest, BlitzApiResponse } from "blitz"
var formidable = require('formidable');
var path = require('path');
var fs = require('fs');

const handler: BlitzApiHandler = async (req: BlitzApiRequest,
  res: BlitzApiResponse) => {
  if (req.method == 'POST') {
    //await runMiddleware(req, res)
    console.log(__dirname);

    const form = new formidable.IncomingForm();
    form.parse(req, function (err, fields, files) {
      const oldpath = files.filetoupload.path;
      const filename = files.filetoupload.name;
      const newpath = path.resolve().split('.blitz')[0] + "/public/" + files.filetoupload.name;
      fs.rename(oldpath, newpath, function (err) {
        if (err) throw err;
        res.write(`File "${filename}" uploaded successfully`);
        return res.end();
      });
 });
  } else {
    res.writeHead(200, {'Content-Type': 'text/html'});
    res.write('<form  method="post" enctype="multipart/form-data">');
    res.write('<input type="file" name="filetoupload"><br>');
    res.write('<input type="submit">');
    res.write('</form>');
    return res.end();
  }

}
export const config = {
  api: {
    bodyParser: false,
  },
};

export default handler

That's it! You should now have a beautiful Blitz.js e-commerce app up and running.

Live demo & GitHub repo

View the Github repo here

View the live demo here

Closing thoughts

Building an app with Blitz.js was a great experience overall. Having the possibility to make an entire app using one framework without having to code a frontend layer was a game-changer.

I thought that features such as "Recipes" were time-saver (and even headache savers at times). Scaffolding based on models also made the development process fast.

I also like the flexibility of using React components, which I would typically find in Next.js.

On the other side, since Blitz.js is built on top of Next.js, which is also built on React, I found that searching for documentation could be a bit confusing at times.

Let me know in the comments what your thoughts are about Blitz and if you have tried building an app with it.

Django for E-Commerce: A Developers Guide (with Wagtail CMS Tutorial)

RealGuillaume — Wed, 01 Sep 2021 18:57:07 +0000

In a rush? Skip to the tutorial, or live demo

“D-J-A-N-G-O. The D is silent.”

Man, I love that line. So badass.

But the eponymous character from Quentin Tarantino’s masterpiece isn’t the only badass Django in town.

So is the popular Python framework of the same name.

Today, we’re leaving the realm of JavaScript frameworks for a quick venture into Django e-commerce.

In this post, I’ll answer legitimate questions you might have when starting a new e-commerce project, such as:

Is Python the right language for my project? What about Django? Is it the right framework? Which tools or plugins should I use?

Then, I’ll show you our homemade recipe for Django-powered e-commerce success with a step-by-step Wagtail CMS and Tailwind CSS tutorial:

Creating a new Wagtail site.
Adding Snipcart configuration settings.
Generating database migrations.
Creating new products for your Django store.
Crafting a Tailwind CSS e-commerce template.

Let’s start with the basics.

The State of Python

One of the main reasons to pick the Django framework is its Python foundation.

A general-purpose, dynamic programming language, Python was developed by ex-Googler Guido van Rossum in the late ’80s. A fan of Monthy Python, he took one-half of the name to baptize his programming project.

How can you not be fans?

He wasn’t joking, though. To say that Python has become “popular” is an understatement.

Today, it’s used by hundreds of thousands of developers all over the world. As StackOverflow puts it:

The term “fastest-growing” can be hard to define precisely, but we make the case that Python has a solid claim to being the fastest-growing major programming language.

A few reasons explain the Python love:

Its grammatical readability is awesome.
It has a fast learning curve for newcomers.
It boasts a long-lasting, solid ecosystem of libraries & community
It’s now the standard language for data science & machine learning.
It powers great dev tools like Pelican, a neat static blog generator.
Reddit is written in Python. 😉

What about the Django framework?

Django is an open-source, high-level Python web framework. Its emphasis on reusable components makes it faster for developers to build web apps on top of Python. It presents itself as a web framework for perfectionists with deadlines.

Now maintained by the Django Software Foundation, it was originally written by two brilliant Lawrence Journal-World developers. Oh, and while Python draws its name from comedy icons, Django got his from a versatile guitar legend: Django Reinhardt!

As a full-stack framework, it overshadows pretty much any alternative tool out there. It’s fast, fully loaded, secure, scalable & versatile. All characteristics you’ll probably want to apply to your e-commerce setup!

Why use Django for e-commerce?

While you can do a lot with Django, let’s keep the focus on what it brings to e-commerce and the different tools available to put together an online store.

First, here are some Django features to consider if you’re looking for the right framework to build a shop.

→ Scalability

Django is perfect for e-commerce startups, as it’s a good fit for small websites and can scale perfectly with business growth. You can rely on Django to handle hundreds/thousands of visitors at a time. It’s built with independent components you can unplug or replace depending on your needs at any specific time.

→ Security

With e-commerce, you want to make sure merchants and clients alike feel safe through your shopping experience. Django prevents a whole lot of common security mistakes, often weakening traditional PHP CMSs. For instance, Django hides your site’s source code from direct viewing on the web by dynamically generating web pages.

→ Feature-rich

Compared to most frameworks, Django comes with way more features out-of-the-box. It allows you to build an app right off the bat. Perfect for supporting your online store with functionalities such as user authentification, content management, or RSS feed. If something seems to be missing, you can count on Django’s community and plugins ecosystem to extend your app!

→ SEO-friendly

SEO is paramount for any online business. Django advocates best practices for SEO. Human-readable URLs and sitemap features are sure to please any marketing team.

Oh, and also, it’s fast, which is always great for both customer experience and SEO.

→ Reliable

It has been crowd-tested for a while now, and the community surrounding it is widely supportive. Active developers continuously update it; maybe you’ll even find yourself contributing.

Django e-commerce tools

There are a few noteworthy e-commerce solutions in the Python/Django ecosystem:

Oscar — Domain-driven e-commerce for Django, open-source.
Saleor — An e-commerce storefront written in Python, open-source.
Django-SHOP — A Django-based shop system.
Shuup — A single and multi-vendor application.

You can explore more options through this extensive list of the best e-commerce packages.

Now let me present you with another cool stack for a complete and custom e-commerce setup with Django.

Wagtail CMS & e-commerce

Wagtail is a developer-first Django content management system. Free and open-source, the good-hearted folks at Torchbox developed it. It’s elegant, flexible, and, IMHO, kicks ass.

In the following Wagtail tutorial, the CMS will be in charge of creating and managing products that users will then be able to buy through a shopping cart.

By the end of it, you’ll have a solid Django-powered e-commerce site up and running.

Let’s get practical!

Django e-commerce tutorial with Wagtail CMS

Over my time at Snipcart, I’ve kind of developed expertise in shopping carts. Why not push it a bit further by creating a shopping cart shop? Let’s see how it goes.

Pre-requisites

A Snipcart account (forever free in test mode)
Python and basic knowledge of it

1. Creating a new Wagtail e-commerce site

Make sure you have Wagtail installed. If not, refer to their installation documentation.

Open a terminal and launch a new Wagtail site:

wagtail start snipcartwagtaildemo
cd snipcartwagtaildemo

We have an extra step to complete the Wagtail setup, and it’s to install the wagtail.contrib.settings plugin that we’ll require later on.

In your new Wagtail project, open the base.py file located in snipcartwaigtaildemo/settings folder. Then, add wagtail.contrib.settings to the INSTALLED_APPS array.

# ./setting/base.py
INSTALLED_APPS = [
    ...,
    ‘wagtail.contrib.settings’
]

1.1 Models definition

The first thing you need to do is create your Page models. Wagtail uses these Django models to generate a page type.

Open the models.py file located in the home folder of your product. This is where you’ll define all your custom models.

Create two different models:

Product: defines the product you’re selling.
ProductCustomField: defines a single product custom field.

Let’s begin by importing the required modules:

# ./home/models.py
from django.db import models

from modelcluster.fields import ParentalKey

from wagtail.core.models import Page, Orderable
from wagtail.admin.edit_handlers import FieldPanel, MultiFieldPanel, InlinePanel
from wagtail.images.edit_handlers import ImageChooserPanel

Now add the Product model:

# ./home/models.py

class Product(Page):
    sku = models.CharField(max_length=255)
    short_description = models.TextField(blank=True, null=True)
    price = models.DecimalField(decimal_places=2, max_digits=10)
    image = models.ForeignKey(
        ‘wagtailimages.Image’,
        null=True,
        blank=True,
        on_delete=models.SET_NULL,
        related_name=‘+’
    )

    content_panels = Page.content_panels + [
        FieldPanel(‘sku’),
        FieldPanel(‘price’),
        ImageChooserPanel(‘image’),
        FieldPanel(‘short_description’),
        InlinePanel(‘custom_fields’, label=‘Custom fields’),
    ]

And ProductCustomField:

# ./home/models.py

class ProductCustomField(Orderable):
    product = ParentalKey(Product, on_delete=models.CASCADE, related_name=‘custom_fields’)
    name = models.CharField(max_length=255)
    options = models.CharField(max_length=500, null=True, blank=True)

    panels = [
        FieldPanel(‘name’),
        FieldPanel(‘options’)
    ]

2. Adding Snipcart configuration settings

If you need more help with this part, refer to our documentation here and here.

Let’s make sure you can update the Snipcart API key directly from Wagtail’s dashboard.

You’ll need to add site settings to do so.

Site settings are special fields that you can add to your models.py file. They’ll appear in the Wagtail Settings section of the dashboard.

Import this module:

# ./home/models.py

from wagtail.contrib.settings.models import BaseSetting, register_setting

Then add these:

# ./home/models.py

@register_setting
class SnipcartSettings(BaseSetting):
    api_key = models.CharField(
        max_length=255,
        help_text=‘Your Snipcart public API key’
    )

3. Database migrations

Now that your models are created, you’ll need to generate database migrations and run them.

In your terminal, use the makemigrations command:

manage.py makemigrations

You should see the following output:

Migrations for ‘home’:  home/migrations/0003_product_productcustomfield_snipcartsettings.py    - Create model Product    - Create model SnipcartSettings    - Create model ProductCustomField

Once the migrations are generated, apply them to your database with the migrate command:

manage.py migrate

It will take a couple of seconds; Wagtail will set up its own database schema along with the models you just defined.

Finally, create your first CMS user with the createsuperuser command:

manage.py createsuperuser

It will ask for an email address, a username, and to create a password. Don’t forget the username and password you picked; you will need them to log into Wagtail’s dashboard.

4. Creating products

Start by firing up your dev server with the Django dev server command:

manage.py runserver

Now open your browser and navigate to http://127.0.0.1:8000/admin. Use the credentials you set up earlier to log in.

Select the Home page in Wagtail’s menu. Then click on the Add child page button.

You’ll be asked to pick a type of page, select Home page and give it a name.

Go back to the Home page menu and click Add child page button under your newly created page.

Once again, you’ll be asked to pick a type of page, this time select Product.

Enter the product details, then publish your new product:

You can create as many products as you wish.

4.1 Adding Snipcart API key

Remember the SnipcartSettings class you created? You’ll be able to configure your API key by expanding the Settings menu and going to Snipcart settings.

Open Snipcart’s dashboard and get your public API key (Test or Live), go back to Wagtail, and paste it in the API key field.

Save your settings.

5. Templating

Your backend is now ready, your API key is configured, and your first products are created—time to start building the site.

For this demo, I decided to use the Tailwind CSS framework. It enables you to build any design directly in your HTML rapidly.

1 - The Tailwind CSS build process

Create a new directory within your Django project, in which you’ll install Tailwind CSS like in any Vanilla.js project setup:

cd your-django-folder
mkdir jstoolchaincd jstoolchain
npm install tailwindcss postcss-cli autoprefixer
npx tailwind init
npx touch postcss.config.js

In this postcss.config.js file located in jstoolchain, add:

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

Then, run:
mkdir css
npx touch css/tailwind.css

In this tailwind.css file, add this:

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

Now, add a script in your jstoolchain/package.json (create a package.json if it’s not already there) file to create the build process and specify the output file, such as:

{
  “scripts”: {
    “build”: “postcss css/tailwind.css -o ../your-django-folder/your-path-to-static/css/tailwind-output.css”
  }
}

Now, run:

npm run-script build

This should run without error, and tailwind-output.css should now be filled with thousands of lines.

Now you can actually use Tailwind CSS classes by including the outputted CSS file into a Django template file along with Django’s call to load the static files:

{% load static %}
<head>
  <link rel=“stylesheet” href=“{% static “css/tailwind-output.css” %}“>
</head>

2 - Handling auto-reload locally

To ease development, what’s missing now is to auto-reload the Django development server when an HTML file is changed and saved. For this, I installed django-livereload-server. Just follow setup instructions. This will work as expected out of the box, without any special configuration.

3 - The purgeCSS process

When you’re ready to deploy, to ensure the CSS output file is not bloated with useless classes, go to jstoolchain/tailwind.config.js file, and add:

  purge: {
    enabled: true,
    content: [‘../your-django-folder/path-to-your-templates/**/*.html’],
  },

Your backend is now ready, your API key is configured, and your first products are created—time to start building the site.

Open the base.html file located in snipcartwaigtaildemo/templates

You’ll need to add references for tailwind-output.css and Snipcart. Add these lines in the head of your document :

<!-- //snipcartwaigtaildemo/templates/base.html -->
{% load static %}
<link rel=“stylesheet” href=“{% static “css/tailwind-output.css” %}“>
{% load static wagtailsettings_tags %}
{% get_settings %}
{# Global stylesheets #}
{# Snipcart #}
{% if settings.home.SnipcartSettings.api_key %}
<script async src=“https://cdn.snipcart.com/themes/v3.2.1/default/snipcart.js”></script>
<div hidden id=“snipcart” data-api-key=“{{ settings.home.SnipcartSettings.api_key }}“></div>
<link rel=“stylesheet” href=“https://cdn.snipcart.com/themes/v3.2.1/default/snipcart.css” />
{% endif %}

The Snipcart API key that you configured previously is available via:

settings.home.SnipcartSettings.api_key

Then, add the navbar and some other tailwind-output.css layout elements.

Replace the body with these lines:

<body class=“{% block body_class %}{% endblock %}“>
    {% wagtailuserbar %}

    <nav class=“bg-white”>
        <div class=“max-w-7xl mx-auto px-2 sm:px-2 lg:px-2">
          <div class=“relative flex items-center justify-between h-16”>
            <div class=“absolute inset-y-0 left-0 flex items-center sm:hidden”>
              <!-- Mobile menu button-->
            <!--
              <button type=“button” class=“inline-flex items-center justify-center p-2 rounded-md text-gray-400 hover:text-white hover:bg-gray-700 focus:outline-none focus:ring-2 focus:ring-inset focus:ring-white” aria-controls=“mobile-menu” aria-expanded=“false”>
                <span class=“sr-only”>Open main menu</span>
            -->
                <!--
                  Icon when menu is closed.

                  Heroicon name: outline/menu

                  Menu open: “hidden”, Menu closed: “block”
                -->
                <svg class=“block h-6 w-6" xmlns=“http://www.w3.org/2000/svg” fill=“none” viewBox=“0 0 24 24” stroke=“currentColor” aria-hidden=“true”>
                  <path stroke-linecap=“round” stroke-linejoin=“round” stroke-width=“2" d=“M4 6h16M4 12h16M4 18h16” />
                </svg>
                <!--
                  Icon when menu is open.

                  Heroicon name: outline/x

                  Menu open: “block”, Menu closed: “hidden”
                -->
                <svg class=“hidden h-6 w-6" xmlns=“http://www.w3.org/2000/svg” fill=“none” viewBox=“0 0 24 24” stroke=“currentColor” aria-hidden=“true”>
                  <path stroke-linecap=“round” stroke-linejoin=“round” stroke-width=“2" d=“M6 18L18 6M6 6l12 12” />
                </svg>
              </button>
            </div>
            <div class=“absolute inset-y-0 right-0 flex items-center pl-0 sm:static sm:inset-auto sm:ml-6 sm:pl-0">
              <div class=“hidden sm:block sm:ml-6”>
                <div class=“flex space-x-4">
                  <!-- Current: “bg-gray-900 text-white”, Default: “text-gray-300 hover:bg-gray-700 hover:text-white” -->
                  <a href=“/shop” class=“hover:bg-gray-200 text-black underline px-3 py-2 rounded-md text-sm font-medium object-left items-left”>Shop</a>
                </div>
              </div>
            </div>
            <div class=“flex-1 flex object-center items-center justify-center sm:items-stretch sm:justify-center px-4”>
              <div class=“hidden sm:block sm:ml-6">
                <div class=“flex-shrink-0 flex object-center items-center”>
                  <a href=“/”><img class=“block lg:hidden h-8 w-auto” src=“/media/original_images/The Shopping Cart Shop nobg Small.svg” alt=“the shopping cart shop”></a>
                  <a href=“/”><img class=“hidden lg:block h-8 w-auto” src=“/media/original_images/The Shopping Cart Shop nobg.svg” alt=“the shopping cart shop”></a>
                </div>
              </div>
            </div>
            <div class=“absolute inset-y-0 right-0 flex items-center pr-0 sm:static sm:inset-auto sm:ml-6 sm:pr-0">

              <!-- Profile dropdown -->
              <div class=“ml-3 relative”>
                <div>
                    <a href=“” class=“hover:bg-gray-200 underline btn btn-primary snipcart-checkout text-black px-3 py-2 rounded-md text-sm font-medium”>
                        <i class=“icon icon-apps”></i>
                        View cart :shopping_trolley: (<span class=“snipcart-items-count”></span>)
                    </a>
                </div>


              </div>
            </div>
          </div>
        </div>

        <!-- Mobile menu, show/hide based on menu state. -->
        <div class=“sm:hidden” id=“mobile-menu”>
          <div class=“px-2 pt-2 pb-3 space-y-1">
            <!-- Current: “bg-gray-900 text-white”, Default: “text-gray-300 hover:bg-gray-700 hover:text-white” -->
            <a href=“/” class=“hover:bg-gray-700 text-white block px-3 py-2 rounded-md text-base font-medium”>Products</a>

          </div>
        </div>
      </nav>

    <div class=“”>
        {% block content %}{% endblock %}
    </div>

    {# Global javascript #}
    <script type=“text/javascript” src=“{% static ‘js/snipcartwagtaildemo.js’ %}“></script>

    {% block extra_js %}
    {# Override this in templates to add extra javascript #}
    {% endblock %}
</body>

5.1 Listing products

The first template you need is your index, where products will be listed.

You’ll have to make your products available in your home page context. In any Wagtail Page, you can override a method name get_context.

You can add the data that the view will receive in parameters. In my case, I want to set the products context variable.

Open the models.py file in the home folder and update the HomePage class:

# ./home/models.py

class HomePage(Page):
    def get_context(self, request):
        context = super().get_context(request)

        context[‘products’] = Product.objects.child_of(self).live()

        return context

Then, open the home_page.html file located in the home/templates/home folder.

Let’s create a simple home page with a button linking to our shop page.

<!-- /.home/templates/home/home_page.html -->
{% extends “base.html” %}
{% load wagtailimages_tags %}

{% block content %}
   <div class=“relative bg-local bg-cover bg-center h-screen”
  style=“background-image: url(media/YOUR_IMAGE)“>
  <div
    class=“justify-center max-w-2xl mx-auto py-8 px-4 sm:py-8 sm:px-6 lg:px-8”>
    <h1 class=“absolute bottom-80 inset-x-0 text-center text-6xl font-normal tracking-tight text-white”>
      The Shopping Cart Shop</h1>
    {% if request.path == ‘/’ %}
    <div class=“absolute bottom-60 left-1/2 transform -translate-x-1/2 -translate-y-1/2”>
      <a href=“/shop”>
        <button class=“bg-white hover:bg-gray-200 text-black font-bold py-2 px-4 rounded”>
          Shop Now
        </button>
      </a>
    </div>
    {% endif %}
{% endblock %}

Now we want to display our products on the shop page with a button linked to the product details. Add this to the home_page.html before {% endlock %} :

<!-- /.home/templates/home/home_page.html -->
{% extends “base.html” %}
{% load wagtailimages_tags %}

{% block content %}

<div class=“relative bg-local bg-cover bg-center h-screen”
  style=“background-image: url(media/original_images/CartCoverLudo-Charles.jpg)“>

  <div
    class=“justify-center max-w-2xl mx-auto py-8 px-4 sm:py-8 sm:px-6 lg:px-8”>
    <h1 class=“absolute bottom-80 inset-x-0 text-center text-6xl font-normal tracking-tight text-white”>
      The Shopping Cart Shop</h1>
    {% if request.path == ‘/’ %}
    <div class=“absolute bottom-60 left-1/2 transform -translate-x-1/2 -translate-y-1/2”>
      <a href=“/shop”>
        <button class=“bg-white hover:bg-gray-200 text-black font-bold py-2 px-4 rounded”>
          Shop Now
        </button>
      </a>
    </div>
    {% endif %}
    <div
      class=“justify-items-center mt-6 grid grid-cols-1 gap-y-10 gap-x-6 sm:grid-cols-2 lg:grid-cols-2 xl:gap-x-8">
      {% for product in products %}
      <div class=“group relative”>
        <div
          class=“w-full min-h-80 bg-gray-200 aspect-w-1 aspect-h-1 rounded-md overflow-hidden lg:h-80 lg:aspect-none”>
          {% image product.image fill-800x1000 as tmp_image %}
          <img src=“{{ tmp_image.url }}” alt=“” class=“img-responsive object-contain w-full h-full”>
        </div>
        <div class=“mt-4 flex justify-between”>
          <div>
            <h3 class=“text-sm text-gray-700 font-bold”>

              <span aria-hidden=“true” class=“absolute inset-0”></span>
              {{ product.title }}

            </h3>
            <p class=“mt-1 text-sm text-gray-800">{{ product.description }}</p>
          </div>
          <p class=“text-sm font-medium text-gray-900”>{{ product.price }}$</p>
        </div>
        <div class=“group-hover:bg-opacity-75 relative left-1/2 transform -translate-x-1/2 -translate-y-1/2 pt-14">
          <a href=“{{ product.get_url }}“>
            <button class=“bg-black hover:bg-gray-800 text-white py-2 px-4 rounded”>
              More Details
            </button>
          </a>
        </div>
      </div>
      {% endfor %}
    </div>
  </div>
</div>
{% endblock %}

5.2 Product details

The last template is the one showing individual product details along with the Snipcart buy button.

Also, it would be nice to be able to select product options directly on this page before adding them to the cart. So I’ll add a way to choose all custom fields with options directly in the template.

Before writing some HTML, you have to update the view context. Django templates don’t give us 100% access to all Python methods and objects, so things like splitting a string do not work very well.

I decided to override the get_context method again. Maybe there’s a better way to do that—let me know in the comments below! 😉

Also, it would be nice to select product options directly on this page before adding them to the cart. So I’ll add a way to choose all custom fields with options directly in the template.

Before writing some HTML, you have to update the view context. Django templates don’t give us 100% access to all Python methods and objects, so things like splitting a string do not work very well.

I decided to override the get_context method again. Maybe there’s a better way to do that—let me know in the comments below! ;)

Open models.py from the home folder and add this method in the Product class:

# ./home/models.py

class Product(Page):

    def get_context(self, request):
        context = super().get_context(request)
        fields = []
        for f in self.custom_fields.get_object_list():
            if f.options:
                f.options_array = f.options.split(‘|')
                fields.append(f)
            else:
                fields.append(f)

        context[‘custom_fields’] = fields

        return context

A custom_fields array will be available in the product.html template.

Create a file named product.html in the home/templates/home folder. This is the template that will be associated with the Product page model.

# ./home/models.py

class Product(Page):

    def get_context(self, request):
        context = super().get_context(request)
        fields = []
        for f in self.custom_fields.get_object_list():
            if f.options:
                f.options_array = f.options.split(‘|')
                fields.append(f)
            else:
                fields.append(f)

        context[‘custom_fields’] = fields

        return context

Then, add some JavaScript to update the Snipcart buy button when a custom field selection is made on the page.

Add the following script snippet before the endblock statement:

<script>
    document.addEventListener(‘DOMContentLoaded’, function () {
        document.querySelector(‘.custom-field-select’).onchange = function (event) {
            if (event.target.dataset.field) {
                document.querySelector(‘.snipcart-add-item’)
                    .dataset[‘itemCustom’ + event.target.dataset.field + ‘Value’] = event.target.value;
            }
        };
    }, false);
</script>

This code updates the button data attributes when the select value changes.

You now have pretty strong foundations to start your e-commerce project using Django and Wagtail!

These frameworks are very powerful; you could quickly add search functionalities, product suggestions, reviews, etc.

Live demo & GitHub repo

See the live demo

See the GitHub repo

Closing thoughts

I really enjoyed working with Wagtail; it’s simple and intuitive. I have to say that their documentation feels incomplete at times, though. At first, I wanted to change how routing would work and haven’t found anything in their docs.

On the other hand, Tailwind CSS was a joy to work with. Their documentation is beautiful, intuitive, and well documented.

I didn’t have the latest version of Python installed on my laptop (a Mac) at the start, so setting up everything and having this demo up and running took me some time. The hosting of the demo was also a bit of a hurdle. I figure it would be way faster for avid Python developers!

For further exploration, I think Wagtail could be a great headless CMS, especially with its built-in API.

Overall I enjoyed my little venture with Django, Wagtail CMS, and Tailwind CSS. I think it could be cool to leverage it and strapping it to tools like Next.js or Gatsby to handle the front end.

Let me know in the comments your experience using these tools.