Forem: prasanna malla

Start your Print-On-Demand business with Printful + Vendure

prasanna malla — Thu, 25 May 2023 23:57:10 +0000

Design custom products using your art, grow your business and sell globally and earn money from home with Printful. Everything is printed and shipped on demand, under your brand! Quickly customize your own branded products using the free Design Maker tool and reach customers globally using their 15 fulfillment centers.

Vendure is a fast growing headless commerce solution with multi-vendor support in the upcoming V2 release on June 07, 2023 allowing you to build your own marketplace like Etsy or Amazon with ease. Today, we will be looking at setting up your own online store for selling print-on-demand products. Signup for a Printful account and create a Manual order platform / API as there is no official platform support for Vendure at this time.

Next, create a Private token over at Printful Developers, select all options under scopes for your store and save the token someplace as it will not be shown once you navigate away from this screen. We will need to add this to the .env file as PRINTFUL_AUTH_TOKEN in our vendure app. If you are new to Vendure, checkout my earlier post to spin up an e-commerce app in under a minute! Now, create your products on Printful and add them to the store.

To start selling your products in under a minute, install the vendure-plugin-printful with yarn add @callit-today/vendure-plugin-printful and add it to the plugins array in vendure-config.ts

AdminUiPlugin.init({
    route: 'admin',
    port: 3002,
    app: compileUiExtensions({
        outputPath: path.join(__dirname, '../admin-ui'),
        extensions: [PrintfulPlugin.uiExtensions],
        devMode: IS_DEV,
    }),
}),
PrintfulPlugin.init({ enabled: true }),

Finally, run yarn dev and go to http://localhost:3000/admin to import your Printful products and start selling! Remember to rebuild search index after import by clicking the gear icon next to the import button.

When an order is placed, printful products are automatically pushed under draft orders and will need to confirm for fulfillment.

Find me on twitter @prasmalla if you have any questions/ feature requests & showcase what you build with it! I look forward to being your customer)👌

PrettyPrint JSON in OSX cli

prasanna malla — Sat, 13 May 2023 18:29:15 +0000

When testing APIs its easy to use curl in your terminal but the output is definitely not pretty. We can pipe the command to python -m json.tool and have it readable but we want it to be pretty)

We will be using homebrew as the package manager to install pygments and python and use this as the default version with pyenv. First we will uninstall any previous version of python installed eg: pyenv uninstall 3.10.5 && pyenv rehash

Let’s start brewing)



brew install @python3.11
cd ~/.pyenv/versions
ln -sfv "$(brew --prefix python@3.11)" 3.11
cd "$(brew --prefix python@3.11)" 
ln -sfv Frameworks/Python.framework/Versions/3.11/include/python3.11 include
cd "$(brew --prefix python@3.11)/bin" 
ln -sfv idle3 idle
ln -sfv pip3 pip 
ln -sfv python3 python
ln -sfv wheel3 wheel
pyenv rehash
pyenv global 3.11
python --version
brew install pygments

Now we can pipe our API call to json.tool for formatting and pygments for JS like colorized output
curl -X GET ‘https://api.printful.com/store/products/307743308' | python -m json.tool | pygmentize -l javascript

Finally, I can get back to writing my next Vendure plugin for Printful! Follow me on twitter @prasmalla for updates on the plugin ✌️

Adding fields to existing types in Vendure

prasanna malla — Sun, 07 May 2023 02:45:00 +0000

Custom fields allow you to add your own custom data properties to many of the Vendure entities. The entities which may have custom fields defined are listed in the CustomFields documentation. While this approach is flexible it becomes quite cumbersome when dealing with a huge number of fields, for example, ingredients for food products. Rather than adding each ingredient as a custom field on the product, we can create an Ingredient entity and have ProductVariant extend it.

import { DeepPartial, ProductVariant, VendureEntity } from '@vendure/core';
import { Entity, Column, ManyToMany, JoinTable } from 'typeorm';

@Entity()
export class Ingredient extends VendureEntity {
    constructor(input?: DeepPartial<Ingredient>) {
        super(input);
    }

    @Column({ nullable: false })
    name!: string;

    @ManyToMany(type => ProductVariant, { nullable: false })
    @JoinTable()
    productVariants!: ProductVariant[];
}

Add the entity, types and resolver to VendureConfig

@VendurePlugin({
    imports: [PluginCommonModule],
    entities: [Ingredient],
    adminApiExtensions: {
        schema: gql`
            type Ingredient implements Node {
                id: ID!
                name: String!
                productVariants: [ProductVariant!]!
            }

            extend type ProductVariant {
                ingredients: [Ingredient!]
            }
        `,
        resolvers: [ProductVariantEntityResolver],
    },
})

Add the field resolver for the ingredients field in ProductVariant entity

import { Parent, ResolveField, Resolver } from '@nestjs/graphql';
import { Ctx, RequestContext, ProductVariant, TransactionalConnection } from '@vendure/core';
import { Ingredient } from '../entity/ingredient.entity';

@Resolver('ProductVariant')
export class ProductVariantEntityResolver {
    constructor(private connection: TransactionalConnection) {}

    @ResolveField()
    ingredients(@Ctx() ctx: RequestContext, @Parent() variant: ProductVariant) {
        return this.connection
            .getRepository(ctx, Ingredient)
            .createQueryBuilder('ing')
            .leftJoin('ing.productVariants', 'variant')
            .where('variant.id = :id', { id: variant.id })
            .getMany();
    }
}

Since Ingredient entity owns the relation, ProductVariant entity does not know about it directly so we are using the above field resolver. Finally, you can query productVariants with ingredients sub-selection.

Vendure v2.0 is coming out soon! come share the excitement on slack.

Adding permissions for Vendure plugins

prasanna malla — Thu, 27 Apr 2023 12:54:12 +0000

Adding permissions for your custom functionality is important for improving the security, compliance, customization, and control of an application. By adding custom permissions, you can create a more personalized and flexible experience for your users and helps you control access to specific features or functionality within your application. Manage user roles, delegating tasks, and ensure that only authorized individuals have access to sensitive data and specified functionality.

In Vendure we can create PermissionDefinitions to create new permissions and require them to specific queries /mutations. Let's create a permission for setting an API key

// apikey-permission.ts

import { PermissionDefinition } from '@vendure/core';

export const apiKey = new PermissionDefinition({
    name: 'SetApiKey',
    description: 'Allows setting API key',
});

Now, we can use @Allow() decorator to limit access to the mutation

// apikey.resolver.ts

import { Allow } from '@vendure/core';
import { Mutation, Resolver } from '@nestjs/graphql';
import { apiKey } from './apikey-permission';

@Resolver()
export class ApiKeyResolver {

  @Allow(apiKey.Permission)
  @Query()
  apiKey() {
    // ...
  }

  @Allow(apiKey.Permission)
  @Mutation()
  setApiKey() {
    // ...
  }
}

And to register apiKey permission in Vendure we pass it to VendureConfig

// apikey.plugin.ts

import gql from 'graphql-tag';
import { VendurePlugin } from '@vendure/core';
import { ApiKeyResolver } from './apikey.resolver'
import { apiKey } from './apiKey-permission';

@VendurePlugin({
  adminApiExtensions: {
    schema: gql`
      type ApiKey {
        id: ID!
        apiKey: String!
      }

      input ApiKeyInput {
        apiKey: String
      }

      extend type Query {
          apiKey: ApiKey
      }

      extend type Mutation {
        setApiKey(input: ApiKeyInput!): ApiKey!
      }
    `,
    resolvers: [ApiKeyResolver]
  },
  configuration: config => {
    config.authOptions.customPermissions.push(apiKey);
    return config;
  },
})
export class ApiKeyPlugin {}

Finally, apiKey permission can be found in the Role detail view of the Admin UI for superadmin, and can be assigned to other Roles as required.

When requiring separate permissions for create, read, update and delete we can use CrudPermissionDefinition which simplifies the creation of the set of 4 CRUD permissions.👌

Using CMS Data Models & Custom Components in Builder.io

prasanna malla — Sun, 23 Apr 2023 21:14:33 +0000

Last time we looked at getting started with Qwik + Builder.io and now it is time to build something with it as a foundation. Onwidget has a nice template for Qwik { ❤️ dark mode } that we will be extending with Builder.io integration. Introducing QwikBuilder, a production ready starter template for building websites with Qwik + Builder.io 😍

Today, we will be creating navigation items to match the templates’ pages and register the hero component to be a cool cat 🙀 lets go!

Go to the Models section in Builder.io and create a ‘Top Menu’ Data model.
Add new ‘Item’ list type field with ‘Url’ as url and ‘Label’ as text for the list item fields. Go the Content section of Builder and add new ‘Top Menu’ and add Services, Portfolio, and About Us as items to match the templates’ pages and publish it. Now, we are ready to implement the code in Qwik

Note: example code at Builder.io does not work at at the time of writing as the SDK is evolving fast and we will need to make some changes



import { Resource, component$, useResource$, useStore } from '@builder.io/qwik';
import { useContent } from '@builder.io/qwik-city';
import { getAllContent } from '@builder.io/sdk-qwik';

export default component$(() => {
  const linksResource = useResource$(() =>
    getAllContent({
      model: 'top-menu',
      apiKey: process.env.BUILDER_PUBLIC_API_KEY as string,
    })
  );

  interface MenuItem {
    label: string;
    url: string;
  }

  return (
    <Resource
      value={linksResource}
      onPending={() => <>Loading...</>}
      onRejected={(error) => <>Error: {error.message}</>}
      // @ts-ignore FIX: after sdk is updated
      onResolved={({ results }) => {
        return (
          // .. header component
          <ul class="dropdown-menu rounded md:absolute pl-4 md:pl-0 md:hidden font-medium md:bg-white md:min-w-[200px] dark:md:bg-slate-800 drop-shadow-xl">
            {results[0].data.item.map(
              ({ label, url }: MenuItem, index: number) => (
                <li key={index}>
                  <a
                    class="font-medium rounded-t md:hover:bg-gray-100 dark:hover:bg-gray-700 py-2 px-4 block whitespace-no-wrap"
                    href={url}
                  >
                    {label}
                  </a>
                </li>
              )
            )}
          </ul>
        )
      }}
    />
  );
});

Only showing the Builder.io bits here, refer to the repo for completed header component. Now, you can add more menu items to show up automatically in qwik app menu, remember to also create pages in Builder.

Custom components allow us to register our existing components and allow for selective editing like just the text copy or call-to-action. While rich text does allow to ‘edit as code’ for custom html/css, it will be erased if the built-in rich text editor is used to make edits to it.

Create a new ‘Homepage’ model in Builder and set Page URL as ‘/’. Register our hero component as custom component in Builder so we can make changes on the fly without the need to re-deploy



import { component$, Resource, useResource$ } from '@builder.io/qwik';
import { useLocation } from '@builder.io/qwik-city';
import {
  getContent,
  RegisteredComponent,
  RenderContent,
} from '@builder.io/sdk-qwik';
// TODO: add back when builder supports avif
// import srcsetAvif from '~/assets/images/hero.jpg?w=400;900&avif&srcset';
// @ts-ignore
import srcsetWebp from '~/assets/images/hero.jpg?w=400;900&webp&srcset';
// @ts-ignore
import { src as placeholder } from '~/assets/images/hero.jpg?width=400&metadata';
import { SITE } from '~/config.mjs';

export const apiKey = process.env.BUILDER_PUBLIC_API_KEY as string;

// let heroSrcsetAvif: string = srcsetAvif;
let heroSrcsetWebp: string = srcsetWebp;

interface HeroProps {
  title1: string;
  title2: string;
  title3: string;
  cta1Text: string;
  cta1Link: string;
}

export const Hero = component$((props: HeroProps) => {
  return (
    <section
      class={`bg-gradient-to-b md:bg-gradient-to-r from-white via-purple-50 to-sky-100 dark:bg-none`}
    >
      <div class="max-w-6xl mx-auto px-4 sm:px-6 md:flex md:h-screen 2xl:h-auto pt-[72px]">
        <div class="py-12 md:py-12 lg:py-16 block md:flex text-center md:text-left">
          <div class="pb-12 md:pb-0 md:py-0 mx-auto md:pr-16 flex items-center basis-3/5">
            <div>
              <h1 class="text-5xl md:text-[3.48rem] font-bold leading-tighter tracking-tighter mb-4 font-heading px-4 md:px-0">
                {props.title1}
                <br class="hidden lg:block" />{' '}
                <span class="hidden lg:inline">{props.title2} </span>{' '}
                <span dangerouslySetInnerHTML={props.title3} />
              </h1>
              <div class="max-w-3xl mx-auto">
                <p class="text-xl text-gray-600 mb-8 dark:text-slate-400">
                  <span class="font-semibold underline decoration-wavy decoration-1 decoration-secondary-600 underline-offset-2">
                    {SITE.name}
                  </span>{' '}
                  is a production ready starter template for building websites
                  using <em>Qwik</em> + <em>Builder.io</em>. It has been
                  designed following Best Practices, SEO, Accessibility,{' '}
                  <span class="inline md:hidden">...</span>
                  <span class="hidden md:inline">
                    Dark Mode, Great Page Speed, image optimization, sitemap
                    generation and more.
                  </span>
                </p>
                <div class="max-w-xs sm:max-w-md flex flex-nowrap flex-col sm:flex-row gap-4 m-auto md:m-0 justify-center md:justify-start">
                  <div class="flex w-full sm:w-auto">
                    <a
                      class="btn btn-primary sm:mb-0 w-full"
                      href={props.cta1Link}
                      target="_blank"
                      rel="noopener"
                    >
                      {props.cta1Text}
                    </a>
                  </div>
                  <div class="flex w-full sm:w-auto">
                    <button class="btn w-full bg-gray-50 dark:bg-transparent">
                      Learn more
                    </button>
                  </div>
                </div>
              </div>
            </div>
          </div>
          <div class="block md:flex items-center flex-1">
            <div class="relative m-auto max-w-4xl md:max-w-sm">
              <picture>
                {/* <source srcSet={heroSrcsetAvif} type="image/avif" /> */}
                <source srcSet={heroSrcsetWebp} type="image/webp" />
                <img
                  src={placeholder}
                  width={1000}
                  height={1250}
                  class="mx-auto w-full rounded-md md:h-full drop-shadow-2xl bg-gray-400 dark:bg-slate-700"
                  alt="QwikBuilder Hero Image (Cool dog)"
                  loading="eager"
                  decoding="async"
                />
              </picture>
            </div>
          </div>
        </div>
      </div>
    </section>
  );
});

export const CUSTOM_COMPONENTS: RegisteredComponent[] = [
  {
    component: Hero,
    name: 'Hero',
    noWrap: true,
    hideFromInsertMenu: false,
    inputs: [
      {
        name: 'title1',
        type: 'string',
        defaultValue: 'Starter template for',
      },
      {
        name: 'title2',
        type: 'string',
        defaultValue: 'building websites with',
      },
      {
        name: 'title3',
        type: 'richText',
        defaultValue: `<span class="text-[#039de1]">Qwik</span> +
        <span class="sm:whitespace-nowrap text-[#039de1]">
          Builder.io
        </span>`,
      },
      {
        name: 'cta1Text',
        type: 'string',
        defaultValue: 'Get template',
      },
      {
        name: 'cta1Link',
        type: 'url',
        defaultValue: 'https://github.com/callit-today/qwik-builder',
      },
    ],
  },
];

export default component$(() => {
  const { url } = useLocation();

  const builderContent = useResource$(() =>
    getContent({
      model: 'homepage',
      apiKey: apiKey,
      userAttributes: { urlPath: url.pathname },
    })
  );

  return (
    <div>
      <Resource
        value={builderContent}
        onPending={() => <>Loading...</>}
        onRejected={(error) => <>Error: {error.message}</>}
        onResolved={(content) => {
          const heroImage =
            // @ts-ignore
            content?.data?.inputs[0]?.defaultValue?.split('?')[0];
          if (heroImage) {
            // heroSrcsetAvif = heroImage + '?format=avif&w=400;900&avif&srcset';
            heroSrcsetWebp = heroImage + '?format=webp&w=400;900&webp&srcset';
          }
          return (
            <RenderContent
              model="homepage"
              content={content}
              apiKey={apiKey}
              customComponents={CUSTOM_COMPONENTS}
            />
          );
        }}
      />
    </div>
  );
});

We are using props to pass the default values from CUSTOM_COMPONETS array to our Hero component which is registered and now available in Builder. Go to contents and select the component under ‘Layers’ tab on the left and click on ‘Options’ tab to edit the custom fields.

Now, click on ‘Data’ tab on the right to add ‘Hero Image’ of type ‘File’ and upload an image. Remember to publish the homepage when done and visit http://localhost:5173 to see the changes

Finally, our hero component is a cool cat all thanks to custom components in Builder.io 😺

Look forward to seeing what you create over at twitter- @prasmalla and let me know what we should do next. Perhaps integrate e-commerce with Vendure 😉

Getting Started with Qwik & Builder.io

prasanna malla — Fri, 21 Apr 2023 21:34:49 +0000

Qwik is the first framework that has similar DX (Developer Experience) as React, Vue or Svelte in authoring components, while delivering Live HTML that is instantly interactive. Qwik applications execute the event handlers on user interaction, without having to bootstrap all the app state, removing the need for hydration completely. This technique is called Resumability. Qwik has instant-on startup performance no matter the application complexity. i.e. Qwik apps deliver the same amount of initial JS regardless of the amount of components. Qwik is the first open-source O(1) framework.

Builder.io, a headless content management system (CMS) and page builder that allows developers and marketers to create and manage dynamic web pages and content without writing any code. It offers a drag-and-drop interface that makes it easy to design and publish pages, while providing a rich set of APIs and integrations for customizing and extending functionality. And developers can easily determine which parts of the storefront are controlled by Builder, who can access them, and what kind of changes they can make. Builder is also compatible with every website or app setup, e-commerce platform, and third-party software, offering several SDKs and robust REST and GraphQL APIs.

pnpm create qwik@latest
pnpm i @builder.io/sdk-qwik
pnpm start

Go to the Models section in Builder.io and create a Page model and use http://localhost:5173/ for Preview URL. Copy the Qwik template to src/routes/[...index]/index.tsx so that it renders all of the Builder pages.

import { component$, Resource, useResource$ } from '@builder.io/qwik';
import { useLocation } from '@builder.io/qwik-city';
import {
  getContent,
  RenderContent,
  getBuilderSearchParams,
} from '@builder.io/sdk-qwik';

export const BUILDER_PUBLIC_API_KEY = YOUR_PUBLIC_API_KEY; // <-- Add your Public API KEY here
export const BUILDER_MODEL = 'page';

export default component$(() => {
  const location = useLocation();

  const builderContentRsrc = useResource$<any>(() => {
    return getContent({
      model: BUILDER_MODEL,
      apiKey: BUILDER_PUBLIC_API_KEY,
      options: getBuilderSearchParams(location.params),
      userAttributes: {
        urlPath: location.url.pathname || '/',
      },
    });
  });

  return (
    <Resource
      value={builderContentRsrc}
      onPending={() => <div>Loading...</div>}
      onResolved={(content) => (
        <RenderContent
          model={BUILDER_MODEL}
          content={content}
          apiKey={BUILDER_PUBLIC_API_KEY}
        />
      )}
    />
  );
});

Make sure to replace YOUR_API_KEY with your Public API Key, which you can find in the Account Settings section of Builder. Qwik is reaching V1 soon and is evolving faster than the docs) change the template with options: getBuilderSearchParams(location.params) and urlPath: location.url.pathname || ‘/’,

In the Content section of Builder, create a new Test Page and select page model. Start with a blank template and add a ‘Hello Qwik From Builder.io’ heading and publish it. Now, visit http://localhost:5173/test-page

Stripping away all the boilerplate examples in the qwik app, we get this clean slate with the content loaded from Builder. Now, we can begin our low-code / no-code, app /page builder journey.

Follow me on twitter @prasmalla for updates to this series where we will build everything from static landing pages, adding a blog with Builder.io as headless CMS, and integrating headless e-commerce with Vendure.

Shipping new features to our NPM package

prasanna malla — Fri, 21 Apr 2023 11:59:44 +0000

Earlier, we published a Vendure plugin to NPM and fixed our first bug. Now, it is time to add new features and publish an update.

On the Todo after extending the AdminUI in Vendure, was the ability for sending back in stock email notifications from the admin. We have the button; let's get to the functionality! All interactions with the server need to be done via GraphQL API calls in the admin ui.

Add the function call to the button and create the notify method

// back-in-stock-list.component.html

<td class="right align-middle">
    <button
        *ngIf="subscription.status === 'Created' && subscription.productVariant.stockOnHand > 0"
        class="icon-button"
        title="Send notification email"
        (click)="notify(subscription.id)"
    >
        <clr-icon shape="envelope"></clr-icon>
    </button>
</td>

// back-in-stock-list.component.ts

async notify(id: ID): Promise<void> {
    try {
        await this.dataService
            .mutate(
                gql`
                    mutation {
                        updateBackInStockSubscription(input: {id: "${id}", status: Notified}) {
                            id
                            status
                        }
                    }
                `,
            )
            .toPromise();
        this.notificationService.success('Notification email sent');
        this.refresh();
    } catch (e) {
        this.notificationService.error('Error');
    }
}

The hard rule is that in an admin UI extension, you cannot import anything from @vendure/core or anything else outside the ui folder. The setup for sending off emails is event driven and came across this hard rule when importing EventBus with this misleading error screen, having nothing to do with other packages as shown. Removing EventBus made this go away

Instead, we publish the BackInStockEvent from the update method in BackInStockService. Email sending from admin works! Next Todo item was limiting emails sent to amount of saleable stock with configurable options.

Vendure is built-on solid foundations using TypeORM with Nest.js which allows us to define database subscribers. With a subscriber, we can listen to specific entity events and take actions based on inserts, updates, deletions and more.

An important factor when working with TypeORM subscribers is that they are very low-level and require some understanding of the Vendure schema. By defining the subscriber as an injectable provider, and passing it to a Vendure plugin, you can take advantage of Nest's dependency injection inside the subscriber methods.

Under the hood, TypeORM uses the Observer design pattern to implement database subscribers. This pattern defines a one-to-many dependency between objects so that when one object changes state, all its dependents are notified and updated automatically. When you register a subscriber, TypeORM sets up database triggers or hooks on the entities that the subscriber is interested in.

When the trigger or hook is fired, the database notifies TypeORM of the event. TypeORM then invokes the corresponding method on the subscriber class, passing in the event data. The subscriber can then perform any custom logic it needs to in response to the event.

This approach is much more efficient than polling the database because it eliminates the need to constantly query the database for changes. Instead, the database itself is responsible for detecting events and notifying the subscribers. This leads to better performance and reduced database load.

Create a subscriber for ProductVariant

/**
 * @description
 * Subscribes to {@link ProductVariant} entity changes
 * and FIFO updates {@link BackInStock} to be notified
 * to the amount of saleable stock with plugin init option
 * limitEmailToStock = true or false to notify all subscribers
 *
 */
@Injectable()
@EventSubscriber()
export class ProductVariantSubscriber implements EntitySubscriberInterface<ProductVariant> {
    constructor(
        private connection: TransactionalConnection,
        private backInStockService: BackInStockService,
        private productVariantService: ProductVariantService,
        private requestContextService: RequestContextService,
    ) {
        this.connection.rawConnection.subscribers.push(this);
    }
    listenTo() {
        return ProductVariant;
    }

    // set subscriptions to be notified only on replenishment event
    async afterUpdate(event: UpdateEvent<ProductVariant>) {
        if (
            event.entity?.stockOnHand > event.databaseEntity?.stockOnHand
        ) {
            const ctx = await this.requestContextService.create({ apiType: getApiType() });
            const productVariant = await this.productVariantService.findOne(ctx, event.entity?.id);
            //! calculate saleable manually as this context is not aware of the current db transaction
            const saleableStock =
                event.entity?.stockOnHand -
                productVariant!.stockAllocated -
                productVariant!.outOfStockThreshold;

            const backInStockSubscriptions = await this.backInStockService.findActiveForProductVariant(
                ctx,
                productVariant!.id,
                {
                    take: BackInStockPlugin.options.limitEmailToStock ? saleableStock : undefined,
                    sort: {
                        createdAt: SortOrder.ASC,
                    },
                },
            );

            if (saleableStock >= 1 && backInStockSubscriptions.totalItems >= 1) {
                for (const subscription of backInStockSubscriptions.items) {
                    this.backInStockService.update(ctx, {
                        id: subscription.id,
                        status: BackInStockSubscriptionStatus.Notified,
                    });
                }
            }
        }
    }
}

@VendurePlugin({
    // .. config
    providers: [
        {
            provide: PLUGIN_INIT_OPTIONS,
            useFactory: () => BackInStockPlugin.options,
        },
        BackInStockService,
        ProductVariantSubscriber,
    ],
})

export class BackInStockPlugin {
    static options: BackInStockOptions = {
        enableEmail: true,
        limitEmailToStock: true,
    };
    static init(options: BackInStockOptions): typeof BackInStockPlugin {
        this.options = options;
        return BackInStockPlugin;
    }
    // .. ui extensions
}

By comparing the stockOnHand on the ongoing DB transaction event.entity and the existing value on event.databaseEntity we can determine replenishment event. Since the new context in the subscriber is not aware of the ongoing DB transaction, we need to change setting saleableStock from ProductVariantService to manual calculation. With the ProductVariantSubscriber added to the providers array and we are ready to test it!

Instead of publishing your changes, you can run yarn build and copy over the dist folder to the node_modules/@callit-today/vendure-plugin-back-in-stock in a test app. Since there is no un-publishing versions in NPM this ensures our new features work and protects against { sometimes 🙋 } forgetting to build before publishing.

Finally, run npm publish and done! You can catch me on Vendure slack for more)

Debugging Node.js with VSCode

prasanna malla — Thu, 20 Apr 2023 22:16:41 +0000

After publishing Back-In-Stock Vendure plugin, we got our first issue reported almost immediately and it happened to be related to an issue with Typescript 3.7+ useDefineForClassFields flag in ts-config breaking Vendure BaseEntity initialization when consuming the plugin.

In a test-app we install the plugin and launch JavaScript Debug Terminal with command palette in Vscode and run yarn dev to start the app with debugger automatically attaching to all the processes. Now set a breakpoint on this line inside node_modules/@callit-today/vendure-plugin-back-in-stock/dist/src/service/back-in-stock.service.js and create a subscription at http://localhost:3000/shop-api and we get this in vsc

Now, that we verified this as the issue, to fix it we remove the useDefineForClassFields flag and set strictPropertyInitialization flag to true in ts-config.json and add definitive assignment assertions (!/?) to the properties in back-in-stock.entity.ts

import { DeepPartial } from '@vendure/common/lib/shared-types';
import { Channel, Customer, ProductVariant, VendureEntity } from '@vendure/core';
import { Column, Entity, ManyToOne } from 'typeorm';
import { BackInStockSubscriptionStatus } from '../types';

/**
 * @description
 * A back-in-stock notification is subscribed to by a {@link Customer}
 * or by a guest user with email address.
 */
@Entity()
export class BackInStock extends VendureEntity {
    constructor(input?: DeepPartial<BackInStock>) {
        super(input);
    }

    @Column('enum', { nullable: false, enum: BackInStockSubscriptionStatus })
    status!: BackInStockSubscriptionStatus;

    @ManyToOne(type => ProductVariant, { nullable: false })
    productVariant!: ProductVariant;

    @ManyToOne(type => Channel, { nullable: false })
    channel!: Channel;

    @ManyToOne(type => Customer, { nullable: true })
    customer?: Customer;

    @Column('varchar', { nullable: false })
    email!: string;
}

While fixing the issue took 2 minutes, triaging the root cause took 2 days. Finally, @michlbrmly set me on the right path over at Vendure slack ❤️ 🙏

"Yeah I hate it when you lose hours of your life to wrestling with tooling. Truly one of the worst aspects of being a dev." - @michlbrmly

Publishing your first NPM package

prasanna malla — Fri, 14 Apr 2023 21:41:44 +0000

Relied upon by more than 17 million developers worldwide, npm is committed to making JavaScript development elegant, productive, and safe. The free npm Registry has become the center of JavaScript code sharing, and with more than two million packages, the largest software registry in the world.

Today, we will be releasing the custom Back-In-Stock plugin for Vendure developed over the past few posts. For starters, we setup a dedicated repo for the plugin and copy over the contents from src/plugins/back-in-stock-plugin/ to the src folder of the new repo and the generated folder to the root of the project, updating path to all files that reference it.

Add README.md with plugin specific details and create a package.json for the plugin to be released. The README might take a while to show up after publishing, this is normal. Notice the name scoped to the user/organization to avoid polluting the global namespace.

{
  "name": "@callit-today/vendure-plugin-back-in-stock",
  "version": "1.0.2",
  "description": "Back-In-Stock Notification Plugin For Vendure",
  "author": "CALLiT.today <plugins@callit.today>",
  "repository": "https://github.com/calliT-today/vendure-plugin-back-in-stock",
  "license": "MIT",
  "private": false,
  "engines": {
    "node": ">=16.0.0"
  },
  "main": "dist/src/index.js",
  "types": "dist/src/index.d.ts",
  "files": [
    "dist",
    "README.md"
  ],
  "scripts": {
    "build": "rimraf dist && tsc"
  },
  "devDependencies": {
    "@vendure/admin-ui-plugin": "1.9.3",
    "@vendure/asset-server-plugin": "1.9.3",
    "@vendure/core": "1.9.3",
    "@vendure/email-plugin": "^1.9.5",
    "@vendure/ui-devkit": "1.9.3",
    "rimraf": "^4.1.2",
    "typescript": "4.9.5"
  }
}

Create a .gitignore file in the project root

__data__
dist
generated/
node_modules

Add a tsconfig.json to the project root

{
  "compilerOptions": {
    "lib": ["es2022"],
    "module": "commonjs",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "target": "es2022",
    "strict": true,
    "sourceMap": false,
    "skipLibCheck": true,
    "types": ["node"],
    "declaration": true,
    "strictPropertyInitialization": false,
    "outDir": "dist"
  },
  "include": ["src/"],
  "exclude": ["src/plugins/**/ui/*"]
}

Before publishing to npm, run yarn to install all the dependencies and verify there are no errors. Now, run yarn build to create the package for distribution in dist folder and commit/push the repo with version tag. Register an account and sign-in with the npm-cli npm login

Finally, we can publish the package with npm publish --access public. The --access flag is required when publishing the first version. Don't forget to yarn build before releasing updates and then you can publish with npm publish without any flags.

Pat yourself in the back! this concludes the series on extending Vendure with custom plugin series. Now, the plugin can be used in any project by running yarn add @callit-today/vendure-plugin-back-in-stock

Share your accomplishments in the Vendure slack channel, look forward to seeing you there!

Admin UI extension in Vendure

prasanna malla — Wed, 12 Apr 2023 19:16:12 +0000

When creating a plugin, we can extend the Admin UI in order to expose a graphical interface to the plugin's functionality.

This is possible by defining AdminUiExtensions. UI extension is an Angular module that gets compiled into the Admin UI application bundle by the compileUiExtensions function exported by the @vendure/ui-devkit package. Internally, the ui-devkit package makes use of the Angular CLI to compile an optimized set of JavaScript bundles containing your extensions. The Vendure Admin UI is built with Angular, and writing UI extensions in Angular is seamless and powerful. But we can write UI extensions using React, Vue, or other frameworks if not familiar with Angular.

Previously, we extended Vendure with a custom Back-In-Stock notification plugin. Now we add a list component to display the subscriptions in the Vendure Admin UI. TypeScript source files of your UI extensions must not be compiled by your regular TypeScript build task. They will instead be compiled by the Angular compiler with compileUiExtensions().
Exclude them in tsconfig.json by adding a line to the "exclude" array

{
  "exclude": [
    "src/plugins/**/ui/*"
  ]
}

Install the ui-devkit package with yarn add @vendure/ui-devkit -D Using GraphQL schema first approach we write our query so that we can use codegen to generate the types for the extension

// src/plugins/vendure-plugin-back-in-stock/ui/components/back-in-stock-list.graphql.ts

import gql from 'graphql-tag';

export const BACKINSTOCK_FRAGMENT = gql`
    fragment BackInStock on BackInStock {
        id
        createdAt
        updatedAt
        status
        email
        productVariant {
            id
            name
            stockOnHand
        }
        customer {
            id
        }
    }
`;

export const GET_BACKINSTOCK_SUBSCRIPTION_LIST = gql`
    query GetBackInStockSubscriptionList($options: BackInStockListOptions) {
        backInStockSubscriptions(options: $options) {
            items {
                ...BackInStock
            }
            totalItems
        }
    }
    ${BACKINSTOCK_FRAGMENT}
`;

Modify codegen.json to add generated-types to the generates object and run it with yarn codegen from the root of the project

// codegen.json

"generated/generated-types.ts": {
    "schema": "http://localhost:3000/admin-api",
    "documents": "src/plugins/**/ui/**/*.graphql.ts",
    "plugins": [
        {
            "add": {
                "content": "/* eslint-disable */"
            }
        },
        "typescript",
        "typescript-compatibility",
        "typescript-operations"
    ],
    "config": {
        "scalars": {
            "ID": "string"
        }
    }
}

Now we can start writing the list component

// src/plugins/vendure-plugin-back-in-stock/ui/components/back-in-stock-list.component.ts

import { ChangeDetectionStrategy, Component } from '@angular/core';
import { ActivatedRoute, Router } from '@angular/router';
import { BaseListComponent, DataService } from '@vendure/admin-ui/core';
import {
    BackInStockSubscriptionStatus,
    GetBackInStockSubscriptionList,
    SortOrder,
} from '../../../../../generated/generated-types';
import { GET_BACKINSTOCK_SUBSCRIPTION_LIST } from './back-in-stock-list.graphql';

// @ts-ignore
@Component({
    selector: 'back-in-stock-list',
    templateUrl: './back-in-stock-list.component.html',
    styleUrls: ['./back-in-stock-list.component.scss'],
    changeDetection: ChangeDetectionStrategy.OnPush,
})
export class BackInStockListComponent extends BaseListComponent<
    GetBackInStockSubscriptionList.Query,
    GetBackInStockSubscriptionList.Items,
    GetBackInStockSubscriptionList.Variables
> {
    filteredStatus: BackInStockSubscriptionStatus | null = BackInStockSubscriptionStatus.Created;

    constructor(private dataService: DataService, router: Router, route: ActivatedRoute) {
        super(router, route);
        super.setQueryFn(
            (...args: any[]) => {
                return this.dataService.query<GetBackInStockSubscriptionList.Query>(
                    GET_BACKINSTOCK_SUBSCRIPTION_LIST,
                    args,
                );
            },
            data => data.backInStockSubscriptions,
            (skip, take) => {
                return {
                    options: {
                        skip,
                        take,
                        sort: {
                            createdAt: SortOrder.ASC,
                        },
                        ...(this.filteredStatus != null
                            ? {
                                  filter: {
                                      status: {
                                          eq: this.filteredStatus,
                                      },
                                  },
                              }
                            : {}),
                    },
                };
            },
        );
    }
}

And add the template for the list component, for adding custom styles use back-in-stock-list.component.scss in the same folder as the html template

// src/plugins/vendure-plugin-back-in-stock/ui/components/back-in-stock-list.component.html

<vdr-action-bar>
    <vdr-ab-left>
        <div class="filter-controls">
            <select clrSelect name="status" [(ngModel)]="filteredStatus" (change)="refresh()">
                <option [ngValue]="null">All Subscriptions</option>
                <option value="Created">Active</option>
                <option value="Notified">Notified</option>
            </select>
        </div>
    </vdr-ab-left>
    <vdr-ab-right> </vdr-ab-right>
</vdr-action-bar>
<vdr-data-table
    [items]="items$ | async"
    [itemsPerPage]="itemsPerPage$ | async"
    [totalItems]="totalItems$ | async"
    [currentPage]="currentPage$ | async"
    (pageChange)="setPageNumber($event)"
    (itemsPerPageChange)="setItemsPerPage($event)"
>
    <vdr-dt-column>ID</vdr-dt-column>
    <vdr-dt-column>Status</vdr-dt-column>
    <vdr-dt-column>Email</vdr-dt-column>
    <vdr-dt-column>Product</vdr-dt-column>
    <vdr-dt-column>Created At</vdr-dt-column>
    <vdr-dt-column>Updated At</vdr-dt-column>
    <ng-template let-subscription="item">
        <td class="left align-middle">
            {{ subscription.id }}
        </td>
        <td class="left align-middle">
            {{ subscription.status }}
        </td>
        <td class="left align-middle">
            <a
                *ngIf="subscription.customer !== null; else guestUser"
                [routerLink]="['/customer', 'customers', subscription.customer.id]"
            >
                {{ subscription.email }}
            </a>
            <ng-template #guestUser>
                {{ subscription.email }}
            </ng-template>
        </td>
        <td class="left align-middle">
            <a
                title="{{ 'Stock on hand - ' + subscription.productVariant.stockOnHand }}"
                [routerLink]="[
                    '/catalog',
                    'products',
                    subscription.productVariant.id,
                    { id: subscription.productVariant.id, tab: 'variants' }
                ]"
            >
                <clr-icon shape="link"></clr-icon>
                {{ subscription.productVariant.name }}
            </a>
        </td>
        <td class="left align-middle">
            {{ subscription.createdAt | date : 'mediumDate' }}
        </td>
        <td class="left align-middle">
            {{ subscription.updatedAt | date : 'mediumDate' }}
        </td>
    </ng-template>
</vdr-data-table>

Let's add the component to it's module

// src/plugins/vendure-plugin-back-in-stock/ui/back-in-stock.module.ts

import { NgModule } from '@angular/core';
import { RouterModule } from '@angular/router';
import { SharedModule } from '@vendure/admin-ui/core';
import { BackInStockListComponent } from './components/back-in-stock-list.component';

// @ts-ignore
@NgModule({
    imports: [
        SharedModule,
        RouterModule.forChild([
            {
                path: '',
                pathMatch: 'full',
                component: BackInStockListComponent,
                data: { breadcrumb: 'Back-In-Stock Subscriptions' },
            },
        ]),
    ],
    declarations: [BackInStockListComponent],
})
export class BackInStockModule {}

And create a shared module for adding a new section to the Admin UI main nav bar containing a link to the extension

// src/plugins/vendure-plugin-back-in-stock/ui/back-in-stock-shared.module.ts

import { NgModule } from '@angular/core';
import { SharedModule, addNavMenuSection } from '@vendure/admin-ui/core';

// @ts-ignore
@NgModule({
    imports: [SharedModule],
    providers: [
        addNavMenuSection(
            {
                id: 'back-in-stock',
                label: 'Custom Plugins',
                items: [
                    {
                        id: 'back-in-stock',
                        label: 'Back-In-Stock',
                        routerLink: ['/extensions/back-in-stock'],
                        // Icon can be any of https://core.clarity.design/foundation/icons/shapes/
                        icon: 'assign-user',
                    },
                ],
            },
            // Add this section before the "settings" section
            'settings',
        ),
    ],
})
export class BackInStockSharedModule {}

Add the modules to the plugins array in vendure-config.ts

// vendure-config.ts

AdminUiPlugin.init({
    route: 'admin',
    port: 3002,
    adminUiConfig: {
        apiHost: 'http://localhost',
        apiPort: 3000,
    },
    app: compileUiExtensions({
        outputPath: path.join(__dirname, '../admin-ui'),
        extensions: [
            {
                extensionPath: path.join(__dirname, '../src/plugins/back-in-stock-plugin/ui'),
                ngModules: [
                    {
                        type: 'lazy' as const,
                        route: 'back-in-stock',
                        ngModuleFileName: 'back-in-stock.module.ts',
                        ngModuleName: 'BackInStockModule',
                    },
                    {
                        type: 'shared' as const,
                        ngModuleFileName: 'back-in-stock-shared.module.ts',
                        ngModuleName: 'BackInStockSharedModule',
                    },
                ],
            },
        ],
        devMode: IS_DEV ? true : false,
    }),
}),

Notice devMode option set to true which will compile the Admin UI app in development mode, and recompile and auto-refresh the browser on any changes to the extension source files.

Angular uses the concept of modules (NgModules) for organizing related code. These modules can be lazily loaded, which means that the code is not loaded when the app starts, but only when that code is required, keeping the main bundle small to improve performance. Shared modules are loaded eagerly, i.e. code is loaded as soon as the app loads. Modules defining new routes must be set to lazy. Modules defining new navigations items must be set to shared.

Finally, run with yarn dev and see the admin UI extension in action at http://localhost:4200/admin/

Read my previous post to learn how the Back-In-Stock plugin was created and join this awesome community of open-source developers on slack to start your own Vendure adventure today!

Extending Vendure's functionality with custom plugins

prasanna malla — Tue, 04 Apr 2023 13:36:44 +0000

TL;DR monkey-patch is monkey-business; use plugin architecture instead!

Monkey-patching is a way to change, extend, or modify software locally. While this may be done as a workaround to a bug or a feature, a better approach is to contribute to the project if it is open-source to help the community and/or if you are writing a new feature, extend it as a custom plugin when/where supported.

Vendure is a modern, open-source headless commerce framework built with TypeScript & Nodejs with an awesome plugin architecture to keep the monkey-business at bay.

Use-case: product inventory goes out of stock; this is a good thing! but when a potential customer sees "out of stock" is when it's not.
Wish-case: let the customer know when the product is back in stock.
Let's build a custom Back-In-Stock plugin!

Here is quick intro to writing a Vendure plugin to get you started with the basics. We will be using the starter plugin-template provided by Vendure for reference to start our journey. Here is the initial plugin setup that includes the entity, GraphQL api extensions, resolver for it and the service that talks to the database. We will be adding email notification here later.



// src/plugins/vendure-plugin-back-in-stock/back-in-stock.plugin.ts

import { PluginCommonModule, VendurePlugin } from '@vendure/core';

import { PLUGIN_INIT_OPTIONS } from './constants';
import { commonApiExtensions } from './api/api-extensions';
import { BackInStockResolver } from './api/back-in-stock.resolver';
import { BackInStock } from './entity/back-in-stock.entity';
import { BackInStockService } from './service/back-in-stock.service';

export interface BackInStockOptions {
    enabled: boolean;
}

@VendurePlugin({
    imports: [PluginCommonModule],
    entities: [BackInStock],
    providers: [
        {
            provide: PLUGIN_INIT_OPTIONS,
            useFactory: () => BackInStockPlugin.options,
        },
        BackInStockService,
    ],
    shopApiExtensions: {
        schema: commonApiExtensions,
        resolvers: [BackInStockResolver],
    },
})
export class BackInStockPlugin {
    static options: BackInStockOptions;

    static init(options: BackInStockOptions) {
        this.options = options;
        return BackInStockPlugin;
    }
}

Define the custom enum type that will be used as status in the entity



// src/plugins/vendure-plugin-back-in-stock/types.ts

export enum BackInStockSubscriptionStatus {
    Created = 'Created',
    Notified = 'Notified',
}

Entity is a class that maps to a database table. You can create an entity by defining a new class and mark it with @Entity()



// src/plugins/vendure-plugin-back-in-stock/entity/back-in-stock.entity.ts

import { DeepPartial } from '@vendure/common/lib/shared-types';
import { Channel, Customer, ProductVariant, VendureEntity } from '@vendure/core';
import { Column, Entity, ManyToOne } from 'typeorm';
import { BackInStockSubscriptionStatus } from '../types';

/**
 * @description
 * A back-in-stock notification is subscribed to by a {@link Customer}
 * or an user with email address.
 *
 */
@Entity()
export class BackInStock extends VendureEntity {
    constructor(input?: DeepPartial<BackInStock>) {
        super(input);
    }

    @Column('enum', { nullable: false, enum: BackInStockSubscriptionStatus })
    status: BackInStockSubscriptionStatus;

    @ManyToOne(type => ProductVariant, { nullable: false })
    productVariant: ProductVariant;

    @ManyToOne(type => Channel, { nullable: false })
    channel: Channel;

    @ManyToOne(type => Customer, { nullable: true })
    customer: Customer;

    @Column('varchar', { nullable: false })
    email: string;
}

After defining a new database entity, we expose the entity in GraphQL API. We add our types, queries and mutations here and will use GraphQL codegen to generate our types later



// src/plugins/vendure-plugin-back-in-stock/api/api-extensions.ts

import { gql } from 'graphql-tag';

export const commonApiExtensions = gql`
    type BackInStock implements Node {
        id: ID!
        createdAt: DateTime!
        updatedAt: DateTime!
        status: BackInStockSubscriptionStatus!
        productVariant: ProductVariant!
        channel: Channel!
        customer: Customer
        email: String!
    }
    enum BackInStockSubscriptionStatus {
        Created
        Notified
        Converted
    }
    input CreateBackInStockEmailInput {
        email: String!
        productVariantId: ID!
    }
    input ProductVariantInput {
        productVariantId: ID!
    }
    type BackInStockList implements PaginatedList {
        items: [BackInStock!]!
        totalItems: Int!
    }
    extend type Query {
        backInStockSubscriptions: BackInStockList!
        activeBackInStockSubscriptionsForProductVariant(input: ProductVariantInput): BackInStockList!
    }
    extend type Mutation {
        createBackInStockSubscription(input: CreateBackInStockInput!): BackInStock!
    }
`;

export const shopApiExtensions = gql`
    ${commonApiExtensions}
`;

export const adminApiExtensions = gql`
    ${commonApiExtensions}
`;

Resolver for the GraphQL query to find all subscriptions



// src/plugins/vendure-plugin-back-in-stock/api/back-in-stock.resolver.ts

import { Inject } from '@nestjs/common';
import { Args, Resolver, Query } from '@nestjs/graphql';
import { RequestContext, Ctx, PaginatedList } from '@vendure/core';
import { loggerCtx, PLUGIN_INIT_OPTIONS } from '../constants';
import { BackInStockOptions } from '../back-in-stock.plugin';
import { BackInStock } from '../entity/back-in-stock.entity';
import { BackInStockService } from '../service/back-in-stock.service';

@Resolver()
export class BackInStockResolver {
    constructor(
        @Inject(PLUGIN_INIT_OPTIONS) private options: BackInStockOptions,
        private backInStockService: BackInStockService,
    ) {}

    @Query()
    async backInStockSubscriptions(
        @Ctx() ctx: RequestContext,
        @Args() args: any,
    ): Promise<PaginatedList<BackInStock>> {
        return this.backInStockService.findAll(ctx, args.options);
    }
}

Service uses methods/functions to perform operations with the model/entity. Here we find all subscriptions and return a paginated list



// src/plugins/vendure-plugin-back-in-stock/service/back-in-stock.service.ts

import { Injectable } from '@nestjs/common';
import { PaginatedList } from '@vendure/common/lib/shared-types';
import {
    ListQueryBuilder,
    RequestContext,
    ListQueryOptions,
    RelationPaths,
    Channel,
    Customer,
    ProductVariant,
} from '@vendure/core';
import { BackInStock } from '../entity/back-in-stock.entity';

/**
 * @description
 * Contains methods relating to {@link BackInStock} entities.
 *
 */
@Injectable()
export class BackInStockService {
    private readonly relations = ['productVariant', 'channel', 'customer'];

    constructor(private listQueryBuilder: ListQueryBuilder) {}

    async findAll(
        ctx: RequestContext,
        options?: ListQueryOptions<BackInStock>,
        relations?: RelationPaths<ProductVariant> | RelationPaths<Channel> | RelationPaths<Customer>,
    ): Promise<PaginatedList<BackInStock>> {
        return this.listQueryBuilder
            .build(BackInStock, options, {
                relations: relations || this.relations,
                ctx,
            })
            .getManyAndCount()
            .then(async ([items, totalItems]) => {
                return {
                    items,
                    totalItems,
                };
            });
    }
}

The following is boilerplate setup common to all plugins



// src/plugins/vendure-plugin-back-in-stock/constants.ts

export const loggerCtx = 'BackInStockPlugin';
export const PLUGIN_INIT_OPTIONS = Symbol('PLUGIN_INIT_OPTIONS');



// src/plugins/vendure-plugin-back-in-stock/index.ts

export * from './back-in-stock.plugin';

Finally, the vendure-config.ts for an example dev server, a starter app created with @vendure/create, using Postgres for database defined in an .env file at the root of the project



// src/vendure-config.ts

require('dotenv').config();
import {
  dummyPaymentHandler,
  DefaultJobQueuePlugin,
  DefaultSearchPlugin,
  VendureConfig,
} from '@vendure/core';
import { defaultEmailHandlers, EmailPlugin } from '@vendure/email-plugin';
import { AssetServerPlugin } from '@vendure/asset-server-plugin';
import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
import path from 'path';
import { BackInStockPlugin } from './plugins/back-in-stock-plugin';

const IS_DEV = process.env.APP_ENV === 'dev';

export const config: VendureConfig = {
  apiOptions: {
    port: 3000,
    adminApiPath: 'admin-api',
    shopApiPath: 'shop-api',
    // The following options are useful in development mode,
    // but are best turned off for production for security
    // reasons.
    ...(IS_DEV
      ? {
          adminApiPlayground: {
            settings: { 'request.credentials': 'include' } as any,
          },
          adminApiDebug: true,
          shopApiPlayground: {
            settings: { 'request.credentials': 'include' } as any,
          },
          shopApiDebug: true,
        }
      : {}),
  },
  authOptions: {
    tokenMethod: ['bearer', 'cookie'],
    superadminCredentials: {
      identifier: process.env.SUPERADMIN_USERNAME,
      password: process.env.SUPERADMIN_PASSWORD,
    },
    cookieOptions: {
      secret: process.env.COOKIE_SECRET,
    },
  },
  dbConnectionOptions: {
    type: 'postgres',
    // See the README.md "Migrations" section for an explanation of
    // the `synchronize` and `migrations` options.
    synchronize: true,
    migrations: [path.join(__dirname, './migrations/*.+(js|ts)')],
    logging: false,
    database: process.env.DB_NAME,
    schema: process.env.DB_SCHEMA,
    host: process.env.DB_HOST,
    port: +process.env.DB_PORT,
    username: process.env.DB_USERNAME,
    password: process.env.DB_PASSWORD,
  },
  paymentOptions: {
    paymentMethodHandlers: [dummyPaymentHandler],
  },
  // When adding or altering custom field definitions, the database will
  // need to be updated. See the "Migrations" section in README.md.
  customFields: {},
  plugins: [
    AssetServerPlugin.init({
      route: 'assets',
      assetUploadDir: path.join(__dirname, '../static/assets'),
      // For local dev, the correct value for assetUrlPrefix should
      // be guessed correctly, but for production it will usually need
      // to be set manually to match your production url.
      assetUrlPrefix: IS_DEV ? undefined : 'https://www.my-shop.com/assets',
    }),
    DefaultJobQueuePlugin.init({ useDatabaseForBuffer: true }),
    DefaultSearchPlugin.init({
      bufferUpdates: false,
      indexStockStatus: true,
    }),
    EmailPlugin.init({
      devMode: true,
      outputPath: path.join(__dirname, '../static/email/test-emails'),
      route: 'mailbox',
      handlers: [...defaultEmailHandlers],
      templatePath: path.join(__dirname, '../static/email/templates'),
      globalTemplateVars: {
        // The following variables will change depending on your storefront implementation.
        // Here we are assuming a storefront running at http://localhost:8080.
        fromAddress: '"example" <noreply@example.com>',
        verifyEmailAddressUrl: 'http://localhost:8080/verify',
        passwordResetUrl: 'http://localhost:8080/password-reset',
        changeEmailAddressUrl:
          'http://localhost:8080/verify-email-address-change',
      },
    }),
    AdminUiPlugin.init({
      route: 'admin',
      port: 3002,
    }),
    // ADD CUSTOM PLUGINS HERE
    BackInStockPlugin.init({ enabled: true }),
  ],
};

Notice BackInStockPlugin added to the plugins array towards the end. Start the server with yarn dev and go to the GraphQL playground at http://localhost:3000/shop-api to find backInStockSubscriptions query.

Now let's setup codegen to generate types from the schema. Create the following json file in the root of your project. Install it with
yarn add -D @graphql-codegen/cli
and run it with
yarn graphql-codegen --config ./codegen.json



// codegen.json

{
    "overwrite": true,
    "config": {
        "strict": true,
        "namingConvention": {
            "enumValues": "keep"
        },
        "scalars": {
            "ID": "string | number"
        },
        "maybeValue": "T"
    },
    "generates": {
        "generated/generated-admin-types.ts": {
            "schema": "http://localhost:3000/admin-api",
            "plugins": [
                {
                    "add": {
                        "content": "/* eslint-disable */"
                    }
                },
                "typescript",
                "typescript-compatibility"
            ]
        },
        "generated/generated-shop-types.ts": {
            "schema": "http://localhost:3000/shop-api",
            "plugins": [
                {
                    "add": {
                        "content": "/* eslint-disable */"
                    }
                },
                "typescript",
                "typescript-compatibility"
            ]
        }
    }
}

Next, we need to add the mutation so we can create some back-in-stock subscriptions. Add the following changes to the resolver and service and remember to import everything missing, your IDE should guide you here



// resolver

@Mutation()
async createBackInStockSubscription(
    @Ctx() ctx: RequestContext,
    @Args() args: MutationCreateBackInStockSubscriptionArgs,
): Promise<BackInStock> {
    return this.backInStockService.create(ctx, args.input);
}



// service

constructor(
    private connection: TransactionalConnection,
    private listQueryBuilder: ListQueryBuilder,
    private channelService: ChannelService,
    private customerService: CustomerService,
    private productVariantService: ProductVariantService,
) {}

async findAll... // This is unchanged

async create(ctx: RequestContext, input: CreateBackInStockInput): Promise<BackInStock> {
    const { email, productVariantId } = input;
    const channel = await this.channelService.getChannelFromToken(ctx.channel.token);
    const customer = await this.customerService.findOneByUserId(ctx, ctx.activeUserId as ID);
    const productVariant = await this.productVariantService.findOne(ctx, productVariantId);

    const backInStockSubscription = new BackInStock({
        email,
        productVariant,
        channel,
        customer,
        status: BackInStockSubscriptionStatus.Created,
    });
    return await this.connection.getRepository(ctx, BackInStock).save(backInStockSubscription);
}

Create a subscription in the shop-api playground

Next, make changes to resolver and service to find active subscriptions



// resolver

@Query()
async activeBackInStockSubscriptionsForProductVariant(
    @Ctx() ctx: RequestContext,
    @Args() args: QueryCreatedBackInStockWithProductVariantArgs,
): Promise<PaginatedList<BackInStock>> {
    return this.backInStockService.findActiveForProductVariant(ctx, args.input.productVariantId);
}



// service

async findActiveForProductVariant(
    ctx: RequestContext,
    productVariantId: ID,
    options?: ListQueryOptions<BackInStock>,
    relations?: RelationPaths<Channel> | RelationPaths<Customer>,
): Promise<PaginatedList<BackInStock>> {
    const productVariant = await this.productVariantService.findOne(ctx, productVariantId);

    return this.listQueryBuilder
        .build(BackInStock, options, {
            relations: relations || this.relations,
            ctx,
            where: {
                productVariant,
                status: BackInStockSubscriptionStatus.Created,
            },
        })
        .getManyAndCount()
        .then(async ([items, totalItems]) => {
            return {
                items,
                totalItems,
            };
        });
}

Finally, we have all the pieces to make the actual use-case work, which is to send an email notification when a subscribed out-of-stock product is replenished. We will leverage the EventBus in Vendure to achieve this



// src/plugins/vendure-plugin-back-in-stock/events/back-in-stock.event.ts

import { ProductVariant, RequestContext, VendureEvent } from '@vendure/core';
import { BackInStock } from '../entity/back-in-stock.entity';

/**
 * @description
 * This event is fired when a {@link BackInStock} is updated
 *
 */
export class BackInStockEvent extends VendureEvent {
    constructor(
        public ctx: RequestContext,
        public entity: BackInStock,
        public productVariant: ProductVariant,
        public type: 'created' | 'updated' | 'deleted',
        public emailAddress: string,
    ) {
        super();
    }
}

Now, update the plugin to listen for events and setup the email handler, remember to import it to vendure-config.ts

handlers: [...defaultEmailHandlers, backInStockEmailHandler]



// back-in-stock.plugin.ts

constructor(
    private eventBus: EventBus,
    private backInStockService: BackInStockService,
    private productVariantService: ProductVariantService,
) {}

/**
 * @description
 * Subscribes to {@link ProductVariantEvent} inventory changes
 * and sends FIFO BackInStock {@link BackInStock} notifications
 * to the amount of saleable stock.
 */
async onApplicationBootstrap() {
    this.eventBus.ofType(ProductVariantEvent).subscribe(async event => {
        for (const productVariant of event.entity) {
            const saleableStock = await this.productVariantService.getSaleableStockLevel(
                event.ctx,
                productVariant,
            );
            const backInStockSubscriptions = await this.backInStockService.findActiveForProductVariant(
                event.ctx,
                productVariant.id,
                {
                    take: saleableStock,
                    sort: {
                        createdAt: SortOrder.ASC,
                    },
                },
            );
            if (saleableStock >= 1 && backInStockSubscriptions.totalItems >= 1) {
                for (const subscription of backInStockSubscriptions.items) {
                    this.eventBus.publish(
                        new BackInStockEvent(
                            event.ctx,
                            subscription,
                            productVariant,
                            'updated',
                            subscription.email,
                        ),
                    );
                    this.backInStockService.update(event.ctx, {
                        id: subscription.id,
                        status: BackInStockSubscriptionStatus.Notified,
                    });
                }
            }
        }
    });
}

// email handler
export const backInStockEmailHandler = new EmailEventListener('back-in-stock')
    .on(BackInStockEvent)
    .setRecipient(event => event?.emailAddress)
    .setFrom(`{{ fromAddress }}`)
    .setSubject(`{{ productVariant.name }} - Back in Stock!`)
    .loadData(async ({ event, injector }) => {
        const hydrator = injector.get(EntityHydrator);
        await hydrator.hydrate(event.ctx, event.productVariant, {
            relations: ['product'],
        });
        return { productVariant: event.productVariant };
    })
    .setTemplateVars(event => ({
        productVariant: event.productVariant,
        url: 'http://localhost:8080/products',
    }));

We are using loadData to hydrate the product variant here so we can use the product's slug in the email template



// static/email/templates/back-in-stock/body.hbs

{{> header title="{{productVariant.name}} - Back In Stock!" }}

<mj-section background-color="#fafafa">
    <mj-column>
        <mj-text color="#525252">
            {{ productVariant.name }} is now back in stock!
        </mj-text>

        <mj-button font-family="Helvetica"
                   background-color="#f45e43"
                   color="white"
                   href="{{ url }}/{{ productVariant.product.slug }}">
            View Product
        </mj-button>

    </mj-column>
</mj-section>

{{> footer }}

Finally, finally, replenish an out-of-stock variant with active back-in-stock subscription at http://localhost:3000/admin and verify the email is being sent at http://localhost:3000/mailbox

I have previously written about getting started with Vendure and contributing to this awesome community of open-source developers.
For further questions, you can ^slack me^ outside :D Happy coding!

Getting started with open source contribution

prasanna malla — Wed, 22 Mar 2023 14:02:55 +0000

The best way to learn anything is by doing and writing code is not any different. While learning to code by making clones of existing software is personally beneficial, there is no use case for all the hard work you put in. Proposal- contribute to open source projects being used by lots of people, now your work will live beyond your portfolio and actually help real users and the community.

Vendure is a modern, open-source headless commerce framework built with TypeScript & Nodejs. And there is a very vibrant and helpful community to get help when you get stuck. Head on over to their github issues to get the current lay of the land and when you find something of interest to you fork the repo and clone it.

Follow the readme to setup your local development environment. Vendure takes testing very seriously - and especially end-to-end (e2e) tests, which provide the maximum guarantee of real-world correctness with currently around 1,400 e2e tests covering all key functionality. You will need some additional packages for Puppeteer to run e2e tests. On a linux machine running ubuntu, install chromium and dependencies.

sudo snap install chromium
sudo apt install -y libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon-x11-0 libxcomposite-dev libxdamage1 libxrandr2 libgbm1 libgtk-3-0 libasound2 libxshmfence-dev

Now you can run the tests with yarn test and yarn e2e it will take a while, that is how well-tested the project is. The best part is you can lookup existing code to learn and write your own features/fixes and tests. Writing tests may look like extra work on the outset but it is a one-and-done approach that ensures your code works now and in the future if breaking changes are introduced, you will not have to re-test manually but rely on these tests you have already written to remedy the breaking changes.

Here is an example test to showcase working with different parts of the app

import { CreateProductInput, ProductTranslationInput } from '@vendure/common/lib/generated-types';
import { createTestEnvironment } from '@vendure/testing';
import path from 'path';

import { testConfig, TEST_SETUP_TIMEOUT_MS } from '../../../e2e-common/test-config';
import { initialData } from '../mock-data/data-sources/initial-data';
import { FastImporterService, LanguageCode } from '../src';

import { GetProductWithVariants } from './graphql/generated-e2e-admin-types';
import { GET_PRODUCT_WITH_VARIANTS } from './graphql/shared-definitions';

describe('FastImporterService resolver', () => {
    const { server, adminClient } = createTestEnvironment(testConfig());

    let fastImporterService: FastImporterService;

    beforeAll(async () => {
        await server.init({
            initialData,
            productsCsvPath: path.join(__dirname, 'fixtures/e2e-products-full.csv'),
        });
        await adminClient.asSuperAdmin();
        fastImporterService = server.app.get(FastImporterService);
    }, TEST_SETUP_TIMEOUT_MS);

    afterAll(async () => {
        await server.destroy();
    });

    it('creates normalized slug', async () => {
        const productTranslation: ProductTranslationInput = {
            languageCode: LanguageCode.en,
            name: 'test product',
            slug: 'test product',
            description: 'test description',
        };
        const createProductInput: CreateProductInput = {
            translations: [productTranslation],
        };
        await fastImporterService.initialize();
        const productId = await fastImporterService.createProduct(createProductInput);

        const { product } = await adminClient.query<
            GetProductWithVariants.Query,
            GetProductWithVariants.Variables
        >(GET_PRODUCT_WITH_VARIANTS, {
            id: productId as string,
        });

        expect(product?.slug).toMatch('test-product');
    });
});

This tests a functionality in the core package, to run this specific test

cd packages/core
yarn e2e fast-importer

Proposal- in your own workflow, write the desired results in a test and run it to see it fail. Now you can write the actual feature/fix and run the test to get it passing. Ship your changes confidently in a pull request and now you are an open source contributor!