Skip to main content

Writing a custom generator

As mentioned in the Overview section, Code Shaper itself is unopinionated about the technologies you use, however plugins usually are. You can choose from the many off-the-shelf plugins designed to work with specific technologies or roll your own to fit your unique needs. In this section, we will explore writing our own plugin to use frameworks and patterns that we prefer.

Use case

In our Movie Magic application, we used a fetch-based hook for fetching movies. A more opinionated approach would be to use react-query and axios for this. Let's write a plugin to generate fetch hooks based on these libraries.

Install react-query and axios

Start by adding react-query and axios to movie-magic. Run the following command in the repository root:

npm install axios @tanstack/react-query --workspace @movie-magic/movie-magic
Using workspaces

Never add a package to a workspace by changing your working directory to that workspace. This will create a package-lock.json file at the workspace level and confuse npm Workspaces. The right way to add a package is to run npm install from the root of the repository and specify the --workspace option.

Now add react-query's QueryClientProvider as a global provider in the application's component tree. Edit main.tsx as follows.

apps/movie-magic/src/main.tsx
import * as React from 'react';
import ReactDOM from 'react-dom/client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { BrowserRouter as Router } from 'react-router-dom';
import { App } from './App';
import './styles/main.css';

// Create a react-query client
const queryClient = new QueryClient();

// Start mock service worker in dev environment
async function startMockServiceWorker() {
if (import.meta.env.DEV) {
const { worker } = await import('./mocks/browser');
await worker.start();
worker.printHandlers();
}
}

startMockServiceWorker().then(() => {
const root = ReactDOM.createRoot(
document.getElementById('root') as HTMLElement
);

root.render(
<React.StrictMode>
<QueryClientProvider client={queryClient}>
<Router>
<App />
</Router>
</QueryClientProvider>
</React.StrictMode>
);
});

Modify useMovies to the desired pattern

The best way to write a generator is to first write out an example of what we want to generate. We can then convert this example into a generic template that can be used repeatedly. So let's start by modifying useMovies to use react-query and axios.

Replace the code in useMovies.ts with the following:

apps/movie-magic/src/pages/HomePage/useMovies.ts
import { useQuery } from '@tanstack/react-query';
import axios from 'axios';
import { Movie } from '../../models';

const apiUrl = import.meta.env.VITE_API_URL;

function fetchMovies(): Promise<Movie[]> {
return axios.get(`${apiUrl}/top-10-movies`).then((response) => response.data);
}

export function useMovies() {
return useQuery(['movies'], fetchMovies);
}

Modify MovieListContainer

Modify MovieListContainer to use useMovies correctly. Replace its contents with the following:

apps/movie-magic/src/pages/HomePage/MovieListContainer.tsx
import * as React from 'react';
import { MovieList } from '../../components';
import { useMovies } from './useMovies';

export function MovieListContainer() {
const movies = useMovies();

if (movies.isLoading) {
return <div>Loading...</div>;
}

if (movies.error) {
return (
<h1 className="text-2xl font-semibold mb-2">
Error:
{movies.error instanceof Error
? movies.error.message
: 'Something went wrong'}
</h1>
);
}

if (!movies.data) {
return <h1 className="text-2xl font-semibold mb-2">No movies found</h1>;
}

return (
<React.Fragment>
<h1 className="text-2xl font-semibold mb-2">Top 10 Movies Of All Time</h1>
<MovieList movies={movies.data} />
</React.Fragment>
);
}

Run the app:

npm run dev

Point your browser to http://localhost:3000. It should look exactly the same as before. The only difference is the implementation of the useMovies hook.

Create a plugin + generator

Now that we have useMovies working again, we know the pattern that needs to be generated. We will have to ask the user a few questions so that we can do proper substitutions in our templates.

Terminology

A plugin can contain one or more generators. For example, a React plugin can generate full react applications, components, contexts and many other artifacts.

Let's start by generating a new plugin and a generator. We will name the plugin react-patterns because it's going to house our custom React patterns.

# Run shaper in the repo's root directory
shaper
? Which plugin would you like to run? Plugin
? Which generator would you like to run? plugin
? Plugin name? react-patterns
? Parent directory? plugins
? Package name used for publishing? @movie-magic/react-patterns

# In the root directory, run:
npm install

# To make sure that everything is set up correctly, run a build
npm run build

# Run shaper again to generate a generator
shaper
? Which plugin would you like to run? Plugin
? Which generator would you like to run? generator
? Generator name? fetch-hook
? Which plugin should this go under? plugins/react-patterns

Register the fetch-hook generator in your react-patterns plugin by editing the index.ts file of your plugin. See highlighted lines below.

plugins/react-patterns/src/index.ts
import {
Options,
Plugin,
Generator,
GeneratorMap,
selectGenerator,
} from '@code-shaper/shaper-utils';
import { fetchHookGenerator } from './fetchHookGenerator';

const generators: GeneratorMap = {};

function registerGenerator(generator: Generator) {
const { id } = generator;
generators[id] = generator;
}

// ----- Register Generators Here -----
registerGenerator(fetchHookGenerator);

const reactPatternsPlugin: Plugin = {
id: '@movie-magic/react-patterns',
name: 'React Patterns',
description: 'generates react-patterns artifacts',
run: async (inputOptions: Options) => {
const generator = await selectGenerator(generators, inputOptions);
if (!generator) {
return Promise.resolve();
}

return generator.generate(process.cwd(), inputOptions);
},
};

export default reactPatternsPlugin;

Rebuild the generator by running the following command in the root directory.

npm run build

Now the generator is ready, but Code Shaper needs to load it dynamically. To make this work, add the react-patterns plugin as a devDependency in the root package.json file of your repo.

package.json
{
...
"devDependencies": {
"@code-shaper/plugin": "latest",
"@code-shaper/react": "latest",
"@code-shaper/shaper-utils": "latest",
"@code-shaper/typescript": "latest",
"@movie-magic/react-patterns": "*",
"husky": "^8.0.1",
"lint-staged": "^12.4.1",
"prettier": "^2.6.2",
"rimraf": "^3.0.2",
"turbo": "latest"
},
...
}

Now run the generator. This is just a trial run. It will not generate anything, so feel free to experiment.

shaper
? Which plugin would you like to run? React Patterns
? Which generator would you like to run? fetch-hook
? Fetch Hook name? useMovies
? Parent directory? apps/movie-magic/src/pages/HomePage

Creating useMovies...

TODO: Run FileUtils.transformFiles() with following arguments:
srcDir: plugins/react-patterns/dist/fetchHookGenerator/templates
dstDir: apps/movie-magic/src/pages/HomePage/use-movies

options available for this generator:
{
"itemName": "useMovies",
"parentDir": "apps/movie-magic/src/pages/HomePage",
"itemNameKebabCase": "use-movies",
"itemNameCamelCase": "useMovies",
"itemNamePascalCase": "UseMovies",
"itemNameCapitalCase": "Use Movies"
}

As you can see, the basic infrastructure for your generator is ready. You may need to tweak the questions a bit, and you will need to write a template. The last part of the output above shows some options available to your templates. Templates use these options as template variables. We will use the terms options and template variables interchangeably. You can tweak them and/or add more.

Tweak the generator

Let's first tweak the generator to customize the questions and the options. See the highlighted lines below:

plugins/react-patterns/src/fetchHookGenerator/index.ts
import { cc, FileUtils, Generator, Options } from '@code-shaper/shaper-utils';
import inquirer from 'inquirer';
// @ts-ignore
import inquirerDirectory from 'inquirer-directory';
import path from 'path';

// Register inquirer prompts
inquirer.registerPrompt('directory', inquirerDirectory);

export const fetchHookGenerator: Generator = {
id: 'fetch-hook',
name: 'Fetch Hook',
description: 'generates a fetch hook',
generate: generateFetchHook,
};

async function generateFetchHook(rootDir: string, inputOptions: Options) {
const questions = [
{
type: 'input',
name: 'itemName',
message: 'What are you fetching? (e.g. "Movie" or "Movies")',
},
{
type: 'input',
name: 'returnType',
message: 'What is the return type? (e.g. "Movie[]")',
},
{
type: 'directory',
name: 'parentDir',
pageSize: 20,
message: 'Parent directory?',
basePath: rootDir,
},
];

const options = await inquirer.prompt(questions, inputOptions);
const { itemName, parentDir } = options;

// --------------------------------------------------------------------------
// Add more options for code generation here
// --------------------------------------------------------------------------
// Assume that the item in this generator is the thing we are fetching.
// Example: itemName = Movies

// itemNameKebabCase = movies
options['itemNameKebabCase'] = cc.kebabCase(itemName);

// itemNameCamelCase = movies
options['itemNameCamelCase'] = cc.camelCase(itemName);

// itemNamePascalCase = Movies
options['itemNamePascalCase'] = cc.pascalCase(itemName);

// itemNameCapitalCase = Movies
options['itemNameCapitalCase'] = cc.capitalCase(itemName);

const { itemNamePascalCase } = options;

// filename = useMovies (then add extension)
options['filename'] = `use${itemNamePascalCase}`;

// hookName = useMovies
options['hookName'] = `use${itemNamePascalCase}`;
// --------------------------------------------------------------------------

const { hookName } = options;

const srcDir = path.join(__dirname, 'templates');
const dstDir = parentDir;

console.log();
console.log(`Creating ${hookName}...`);

// Create the hook
FileUtils.transformFiles(srcDir, dstDir, options);

console.log();
console.log('Done.');
console.log();
console.log(`You can start using ${hookName} in your app`);
console.log();

return Promise.resolve();
}

Write a template

Now that the generator is creating a good set of options, we can write a template to generate the fetch hook. Start with useMovies.ts and generalize it to fetch any type of object.

Templates

In this example we have only one template. However, in more complex scenarios we may have multiple templates spread over a nested tree structure. Code Shaper can handle such scenarios without breaking a sweat!

Create a folder called templates under the fetchHookGenerator and copy useMovies.ts under it. Specifically, copy apps/movie-magic/src/pages/HomePage/useMovies.ts to plugins/react-patterns/src/fetchHookGenerator/templates/useMovies.ts.

Now rename this file to [filename].ts.ejs.t. Why? Remember that our generator outputs a filename option. When the generator copies this file over to the destination, it will replace the [filename] part with that option. Moreover, the .ejs.t suffix tells the generator to do option substitutions before copying the file over. The suffix will be removed. What does this all mean? If the value of the filename option is useMovies, the file created at the destination will be called useMovies.ts - which is exactly what we want.

Static Templates

If you want to copy a template without any option substitutions, do not add the .ejs.t suffix to it. For example, a file called favicon.ico will be copied as is, without any substitutions.

Finally, edit [filename].ts.ejs.t to turn it into a template. Here's the final content:

import { useQuery } from '@tanstack/react-query';
import axios from 'axios';

const apiUrl = import.meta.env.VITE_API_URL;

function fetch<%= itemNamePascalCase %>(): Promise<<%= returnType %>> {
return axios.get(`${apiUrl}/<%= itemNameKebabCase %>`).then((response) => response.data);
}

export function <%= hookName %>() {
return useQuery(['<%= itemNameCamelCase %>'], fetch<%= itemNamePascalCase %>);
}

Test the generator

Let's write a test for our fetchHookGenerator. A placeholder test is already provided for us. Edit it to add the generator specific options:

plugins/react-patterns/src/fetchHookGenerator/fetchHookGenerator.test.ts
import path from 'path';
import { FileUtils } from '@code-shaper/shaper-utils';
import { fetchHookGenerator } from './index';

describe('fetchHookGenerator', () => {
test('should create a new fetchHook from templates', async () => {
// suppress console logs
// eslint-disable-next-line @typescript-eslint/no-empty-function
jest.spyOn(console, 'log').mockImplementation(() => {});

// Delete test-output if it exists
const testOutput = path.join(__dirname, 'test-output');
FileUtils.deletePath(testOutput);

// Run the generator
await fetchHookGenerator.generate(testOutput, {
itemName: 'Movies',
returnType: 'Movie[]',
parentDir: path.join(testOutput),
});

// Compare test-output with expected-output
const expectedOutput = path.join(__dirname, 'expected-output');
const result = FileUtils.compareDirectories(expectedOutput, testOutput);
expect(result.same).toBe(true);

// restore console logs
jest.restoreAllMocks();
});
});

Build & test:

npm run build
npm test

The test generates its output at plugins/react-patterns/src/fetchHookGenerator/test-output/useMovies. However, it fails because there is no expected-output folder to compare against.

Let's first make sure that the generated output in useMovies.ts matches the code shown below:

import { useQuery } from '@tanstack/react-query';
import axios from 'axios';

const apiUrl = import.meta.env.VITE_API_URL;

function fetchMovies(): Promise<Movie[]> {
return axios.get(`${apiUrl}/movies`).then((response) => response.data);
}

export function useMovies() {
return useQuery(['movies'], fetchMovies);
}

Assuming the code matches, rename the test-output folder to expected-output. We are essentially capturing a snapshot of what the output should look like. Now rerun the test.

npm test

It should pass this time because test-output should match expected-output exactly.

Generate useMovies

Now let's generate the real useMovies hook in the app. Delete the existing useMovies hook that we handwrote (apps/movie-magic/src/pages/HomePage/useMovies.ts). Regenerate it using our new fetch-hook generator:

shaper
? Which plugin would you like to run? React Patterns
? Which generator would you like to run? fetch-hook
? What are you fetching? Movies
? What is the return type? Movie[]
? Parent directory? apps/movie-magic/src/pages/HomePage

Creating useMovies...
useMovies.ts

Done.

You can start using useMovies in your app

Here's the generated output, along with a couple of minor tweaks needed to make it work. That's completely fine - we need to balance the effort vs. the perfection we want to achieve!

import { useQuery } from '@tanstack/react-query';
import axios from 'axios';
import { Movie } from '../../models';

const apiUrl = import.meta.env.VITE_API_URL;

function fetchMovies(): Promise<Movie[]> {
return axios.get(`${apiUrl}/top-10-movies`).then((response) => response.data);
}

export function useMovies() {
return useQuery(['movies'], fetchMovies);
}

Run the app:

npm run dev

Point your browser to http://localhost:3000. It should look exactly the same as before. The only difference is that the useMovies hook is now auto-generated.

Commit your code

# Commit
git add .
git commit -m "Added react-patterns plugin and fetch-hook generator"

Congratulations! You have now learned how to write Code Shaper plugins and generators.