[RFC] Blitz Recipes (formerly Installers)

[flybayer]

Problem

There's hundreds of tools and libraries that different people want to integrate with their app.

Next.js solves this problem by having all these integrations as example apps. This works fairly well, but it's still cumbersome to go find the proper example, copy the code, paste the code, try it, go back and copy something you forgot to copy, and finally get it working.

Solution

Add the blitz install command that can run any available installer.

Examples:

blitz install tailwind
blitz install styled-components
blitz install emotion
blitz install theme-ui
blitz install sentry
blitz install storybook
blitz install auth0
blitz install fauna

The two most common things performed by an installer are:

1. Install npm dependencies
2. Add or update files

Implementation

At the most basic level, an installer is a plain Node script. But we'll provide utilities that make it easy to write an installer.

• Installers will be hosted in an official Blitz repo
• When an installer is invoked, the blitz cli will download it from github and run it
• We could also add ability to use private installers from a private repo or private npm package

Installer helpers:

1. installDependencies and installDevDependencies — will automatically use npm or yarn based on the project
2. File create and update helpers

Perhaps we could have a @blitzjs/installer package to import the helpers from. It would always be available in a blitz app for the installer to use.

Feedback

I'd love to hear all your comments on this. Love it? Hate it? Ideas on making this better?

[ghost]

Why not npm install?
How is blitz install different from it?

[remidej]

Sounds great!

I wonder how apps that already have custom code will be handled. Sounds like Blitz will need some kind of conflict resolution system.

Why not npm install?
How is blitz install different from it?

npm can only install packages in node_modules and save the dependencies in package.json.

Having this in the CLI also allows us to also generate the boilerplate in our code.

[aminbenselim]

some of the items in the list seem to be of the same category (styled-components, emotion, or for example auth0 and firebase auth which is not mentioned). so adding two of them does not make sense.
How about creating a sane categorization for these installers:
blitz install --css-in-js emotion --auth auth0 --cms prismic

[NateRadebaugh]

Sounds like Gatsby recipes. Does it make sense to standardize on a similar format for this? Eg MDX with custom components for install vs update

[cristianbgp]

Sounds great! But I'm thinking if we can try another solution to still use npm install (or yarn) to install the dependencies but add a generator to update or add files for that package.

Something similar in Rails

gem 'devise'
rails generate devise:install

Maybe we can still have

npm install tailwind or yarn add tailwind
and then use the generator to generate the boilerplate
blitz generate tailwind:install

[toddgeist]

does this solve the plugins case?

[flybayer]

I wonder how apps that already have custom code will be handled. Sounds like Blitz will need some kind of conflict resolution system.

@remi2j Yes, it'll definitely have some type of nice conflict resolution system.

some of the items in the list seem to be of the same category (styled-components, emotion, or for example auth0 and firebase auth which is not mentioned). so adding two of them does not make sense.

@amine-benselim Yes, I've just listed them as various examples, not as things someone would all use at once.

I wonder how apps that already have custom code will be handled. Sounds like Blitz will need some kind of conflict resolution system.

@NateRadebaugh Gatsby recipes are only docs right? Blitz installers are code generators, not docs.

Maybe we can still have

npm install tailwind or yarn add tailwind
and then use the generator to generate the boilerplate
blitz generate tailwind:install

@cristianbgp The problem with this approach is that the tailwind npm package would have to package the blitz specific code. And they will never do that in the main package. Unfortunately this is a different landscape than the Rails/Gem one.

does this solve the plugins case?

@toddgeist no. Installers often won't hook into Blitz at all. Mostly they will install a dependency or two and scaffold a bit of code.

Plugins on the other hand will hook into various parts of blitz. An installer could also install a plugin.

I'll post another RFC soon for plugins

[wKovacs64]

Gatsby Recipes install dependencies and write to files. Not sure if they line up exactly with what you have in mind for Blitz Installers, but sounds pretty close!

[flybayer]

Oh wow, yes! Googling “Gatsby Recipes” takes you to a docs section that’s titled “Gatsby recipes” lol

Looks like pretty much the same thing as what I’m proposing!

Not sure how I feel about MDX for this tho 🤔 Seems limiting and extra complexity for what can be a regular node script. But I could be convinced otherwise :)

[Mozart409]

Hi,
I added a very rough plugin to add tailwindcss. No edge cases are covered, does not install dependencies, just writes some files to specific folders.

• postcss.config.js
• tailwind.config.js
• app/style.css

Prepends import '../style.css' to app/pages/_app.tsx

Tell me what you think and let's build this together via PRs 👍

https://github.com/Mozart409/blitzjs-tailwind-installer

[fraserdrops]

When I saw this RFC Gatsby recipes were the first thing that came to my mind as well. Reading the announcement blog, it seems like the MDX syntax is mainly for readability. The heavy-lifting looks like it's being done by an xState machine to control the flow for running a recipe.

[ryardley]

I think some in the community will really appreciate this and it will definitely save time in many cases but I must say I love the way next has all their examples in their repo and I still think we should give people the option of copying code from an example to apply it (even if the examples were just generated from running the installation scripts) Perhaps I am paranoid around combinations of automation breaking or I really find comfort in understanding how a plugin is actually integrated.

[flybayer]

@ryardley we could only run an installer if the git repo is clean. Then git diff will show you exactly what the installer did.

[lukasluecke]

Also similar to what https://flex.symfony.com is providing for Symfony Bundles, their options and configuration is documented at https://github.com/symfony/recipes/blob/master/README.rst.

They actually hook into the package installation to find matching recipes automatically, not sure if that's something we could also accomplish in a postinstall-hook or something?

They also show a note after installation to check (with git diff or similar) and modify the added files if necessary, which in practice is a lot nicer than having to copy/paste several things from/to different files and directories - and still allows you to check what is added before committing it.

[Skn0tt]

When an installer is invoked, the blitz cli will download it from github and run it

Could you elaborate on the advantages of distributing via Git vs using NPM?

Also, as the code to be generated depends on the version of Blitz used, there will be the need for some kind of versioning with the generator scripts.

[flybayer]

@aem nice!! So what would an actual installer look like?

[aem]

knew I forgot an example 🤦‍♂️something like this, assuming findNextDocumentTSXFile is a function that uses the jscodeshift API to return a list of filenames and addMyLibSetup adds some reasonable code to each file returned by selectTargetFiles:

import { Installer } from '@blitz/installer'

enum Steps {
  addDep,
  addPostcssConfig,
  addSampleStyles,
  import,
}
export default new Installer(
  [
    {
      stepId: Steps.addDep,
      stepName: 'Add tailwind dependencies',
      explanation: 'Install tailwind and related postcss dependencies',
      packages: ['tailwindcss@1', '@fullhuman/postcss-purgecss', 'postcss-preset-env'],
    },
    {
      stepId: Steps.addPostcssConfig,
      stepName: 'Add postcss config',
      explanation: 'Configure the postcss processor',
      templatePath: path.join(__dirname, 'templates', 'postcss-config'),
      destinationPath: '.',
    },
    {
      stepId: Steps.addSampleStyles,
      stepName: 'Add example style files',
      explanation: "We'll add some example styles to get you up and running",
      templatePath: path.join(__dirname, 'templates', 'styles'),
      destinationPath: './app/styles',
    },
    {
      stepId: Steps.import,
      stepName: 'Import styles into app',
      explanation:
        "Finally we need to import your styles into the app. For our sample files, we'll import them into your app root.",
      // any installer field can either be a static property or a function that accepts the
      // CLI args and returns the same type as the static property
      singleFileSearch(cliArgs: any) {
        return cliArgs.appRootPath
      },
      transform(fileInfo, api) {
        // these lines are standard in the codemod - access the jscodeshift API
        // and extract the file's source as an AST
        const j = api.jscodeshift
        const fileRoot = j(fileInfo.source)
        // this defines an import statement, the empty array means no import specifiers
        // since we're not importing any variables into the namespace
        const stylesImport = j.importDeclaration([], j.literal('app/styles/index.css'))
        // we can probably supply a generic utility for adding an import to a file,
        // installer authors shouldn't need to rewrite this from scratch
        addImport(fileRoot, j, stylesImport)
      },
    },
  ],
  {
    packageName: 'tailwind',
    packageDescription: 'Installs tailwind CSS and adds necessary setup code to application.',
    packageRepo: 'https://github.com/blitz-js/installers',
    packageOwner: 'adam@markon.codes',
    async validateArgs(args: any) {
      if (!args.appRootPath) {
        throw new Error(
          '[tailwind installer]: please supply --appRootPath. Usually this is app/pages/_app.tsx',
        )
      }
    },
  },
)

I have the package metadata fields in there so that we can log some useful information to the user - "this installer is provided by {{owner}} and will install {{packageName}}. See more at {{repo}}", etc

[flybayer]

Ok cool — looks promising! Could you update that for tailwind specifically? Would be easier to grok than my-lib :) @aem

[flybayer]

Would findNextDocumentTSXFile and addMyLibSetup be written in the custom installer code or the blitz installer package?

[merelinguist]

@aem I’d love to see what that looks like for tailwind too. FYI, the steps for setting it up in a Next.js / Blitz app normally are documented well here: https://github.com/tailwindcss/setup-examples/tree/master/examples/nextjs.

[flybayer]

@aem @merelinguist we already have a Blitz tailwind example at examples/tailwind

[aem]

Would findNextDocumentTSXFile and addMyLibSetup be written in the custom installer code or the blitz installer package?

Could theoretically be either. I'd guess eventually we'll see some common patterns and want to build out some shared utilities, but initially we'll probably have installer authors write their own. That example was a quick and dirty version, but I should be able to get something more realistic written up that actually uses the jscodeshift API today.

[aem]

@flybayer @merelinguist I updated the example to use tailwind, which is much clearer, less contrived, and honestly that code could probably be copy-pasted into the official tailwind installer once the installer internals are built out. I added some comments for things that aren't obvious in the example since it doesn't have typescript types

[aem]

But having said that, it does compile! Locally all of the types check properly e2e, including the installer scaffolding from my RFC gist

[flybayer]

@aem awesome!!

• We need a way to set packages as regular or dev dependencies
• We can auto provide the path to _app.tsx and _document.tsx (look it up for them)

[aem]

@flybayer for sure! i think a lot of that stuff will be fleshed out more during implementation, the idea here was just to give an idea of what the API/step framework looks like

[aem]

If there's no other significant concerns about the architecture here I'll proceed with this implementation. Should have something installer-esque by the end of the weekend

[flybayer]

@aem sounds glorious!

[aem]

Wanted to provide a quick update for everyone based on an exciting meeting we had with the folks over at Gatsby earlier today. Some bullets from my notes:

• Everyone agreed there's an easy opportunity for collaboration here. While we have slightly different visions for how exactly recipes fit into the lifecycle of a Blitz/Gatsby website, the core idea is identical and we can all benefit from the collaboration
• The eventual goal is to combine MDX with a custom React renderer so you can actually write recipes delcaratively as React components! The Gatsby folks are super excited by this, as were @flybayer and I
• The next iteration of recipes is taking a lot of inspiration from Terraform - the idea that you describe your application/system state and then your application just resolves that state declaration into something usable. For Terraform that's cloud resources, for us that's npm packages and codemods
• The Gatsby team previously hadn't been thinking about codemods being a part of the core framework the way we were, but they're liking the idea and want to adopt that into the Gatsby recipes framework. They seemed excited when we explained how our tailwind recipe actually imports the CSS file directly into the app so you can use it right away.
• Once I wrap up my outstanding issues for the CLI I'll transition into more dedicated hours on the installer, working with @johno to generalize the recipe framework + renderer into something that will be shared cross-platform as well as a small library of core components (add npm deps, for example), and then most components will be platform specific.
• Their team is fine with us calling them Blitz Recipes the same way they call them Gatsby Recipes :) The one ask is that we give them some credit which is completely reasonable (and was our plan anyway) given that a lot of our design choices stem from the experience they've created.

@flybayer anything I missed?

[aem]

One more interesting piece here - their vision for recipes is an interesting blurring of the line as far as how we were thinking about installers vs. plugins. We had a vision that they were two separate concepts, a one-time installation vs. an ongoing integration. Gatsby obviously already has a plugin architecture, but it seems like their goal for installers is that they become a part of your project and can be re-run regularly, potentially continuing to upgrade/update your codebase. I don't think this affects our plans at all, it's just an interesting idea that installers stay a part of your app, even if only via a lockfile of some kind, and can provide ongoing functionality beyond when you first run the CLI.

[toddgeist]

whats a good resource to get up to speed on the core ideas behind recipes?

[toddgeist]

• https://www.gatsbyjs.org/blog/2020-04-15-announcing-gatsby-recipes/
• Gatsby Recipes gatsbyjs/gatsby#22991