Custom Generators

[cannikin]

At long last you can customize your generators! This PR adds a new command, the awesomely named Generator generator generator setup command:

yarn rw setup generator page

Running that generator will create a lib/generators directory in either web or api depending on which side the generator applies to. It then copies the template files for that generator into the directory.

For example, the above command would create:

my-app/
├─ api/
└─ web/
   └─ generators/
      └─ page/
         ├─ stories.tsx.template
         ├─ test.tsx.template
         └─ page.tsx.template

Then when the actual generator is run it will look in that location first and if a template is present, use it. Otherwise it'll fall back to the one built into Redwood.

The list of generators you can customize:

• cell
• component
• function
• layout
• page
• scaffold
• sdl
• service

Limitations

For all of the generators except scaffold, you can overwrite as many or as few of the templates as you want. You might override the page component file, but not care about stories or tests. You can delete those custom templates in your app directory and be good to go.

But, because of way files are looked up for the Scaffold generator, if you want to customize any of the pages/cells/components, you'll need to have every scaffold template in a single template subdirectory (assets, components, layouts, pages) present in your custom directory.

Single subdirectory? That means if you want to customize any of the pages generated with a scaffold, you need all of them present in web/src/lib/generators/scaffold/pages. You can delete the other directories (assets, components, layouts) if you want, but if you want to customize any single file in one of those dirs you'll need all the templates within.

I'm guessing this probably isn't an issue as people that want to customize will probably want to update the UI across all of the scaffold, but we should definitely note it in the release notes/docs (or spend more time changing how the scaffold looks up template files so that it behaves like the others).

Closes #914

[callingmedic911]

This is awesome!

Just a random thought: I was wondering if we can also pass custom variable for these templates? For example, template has ${customPrefix} in use, and then somehow pass variable via CLI yarn rw g generator page customPrefix=nicePrefix. What do you think?

[cannikin]

I was wondering if we can also pass custom variable for these templates? For example, template has ${customPrefix} in use, and then somehow pass variable via CLI yarn rw g generator page customPrefix=nicePrefix. What do you think?

I love this idea and will attempt to add it! I'm hoping yargs has some kind of "glob" syntax that just scoops up all other variables and provides them...we've only ever used it with named/positional arguments where you have to know all the variable names ahead of time...

[dac09]

Hey @cannikin not reviewed this properly, but for me the custom templates shouldn't be in src.

I think it would be nice to have this structure

my-app/
├─ api/
   └─ templates # < --- houses the custom templates for API
└─ web/
   └─ src/
   └─ types # <--- has all the web types
   └─ templates # < --- houses the custom templates for Web

[cannikin]

Hey @cannikin not reviewed this properly, but for me the custom templates shouldn't be in src.

Hmm, I'm no expert on Javascript directory conventions, but I thought everything that isn't specifically a user-interface for My App should go in a lib, and right now we have src/lib in api so I assumed we'd use the same structure for web. Is it actually the wild west and we can do whatever we want?

I don't love the folder name just being templates as that's pretty generic (what if my own site has templates?). I really want to put them in generators so it's much more clear what the files in there are for.

[dac09]

Folder name totally fine with whatever you pick - but I just don't think it should be src, which houses run time code only (typically).

[cannikin]

Okay cool, I'll move then! BRB

[cannikin]

@dac09 Moved! Updated the first comment to reflect new location.

[thedavidprice]

Looping in @dthyresson

@cannikin Nice work on this! Would be great to demo at the next Core Team — I'll add it to the agenda. And TBD as needed.

[cannikin]

@callingmedic911 : I was wondering if we can also pass custom variable for these templates?

I do wanna do this, but I'd like to get this out first and have a followup PR for custom variables. It's gonna take a little more work than I anticipated and don't want to hold this one up!

[callingmedic911]

Totally! Maybe we can get more feedback from the community before adding the feature. In any case, let me know if I can be of any help. :)

[cannikin]

We're going to move this to a setup command instead (first comment/description updated)!

[cannikin]

Okay we gotta hurry and merge this before CI breaks again. :)

[thedavidprice]

yarn rw setup generator page

I thought setup template was the final decision?

I'm fine either way. Just sanity check.

[cannikin]

Last thing I heard was @mojombo liked setup generators because you actually are setting up the generator, which for now is just overriding the template. I thought! Let me ping him...

Confirmed from Tom: setup generator