This is an outline of an idea for an example app and tutorial in response to this tweet from @thedavid:
What would be an ideal Example App for @redwoodjs? The current Tutorial walks through creating a blog ('cause classic example, am I right?), which has the breadth but isn’t specifically app-like.
I’d like to explain the idea I have for the example app and ask for input on the different parts of that idea.
Comments From The Twitter Thread:
-
“It’s crucial that it be very beginner friendly.”
-
“Something with roles like admin, staff, anonymous etc. RBAC is coming up. A lot.”
-
“Something with relationships.”
-
“CRUD for sure.”
-
“What I like about [providing data through forms, Geo IP, or File upload for processin then doing stuff to that data and updating a live feed] is how they would highlight the versatility of Redwood’s API.”
-
“[If payments are involved] without a quick setup/package the Tutorial would turn more into how to integrate vs. how to build a thing.”
-
“Pagination is more of a pain than it needs to be. But maybe we should have a built-in helper or generator for this.”
Background on a Newsletter App
Newsletters typically use email marketing platforms like ConvertKit, HubSpot, or MailChimp. Those platforms are focused on implementing marketing funnels from a subscription list. They have built-in editors that help with writing HTML emails to work across email clients like Outlook and GMail, provide HTML snippets for subscription sign-ups, and REST APIs for other integrations.
One pain point is an easy way for people to set up a page on their website with archived newsletters and the ability to read individual archived newsletters. Redwood uses the built-in MailChimp pages for its own newsletter archive list and item view pages.
I think this is a good candidate for a tutorial app for three reasons:
-
It covers a pretty broad range of functionality, while still being fairly narrow in scope.
-
It’s possible that Redwood could dogfood the app.
-
It’s something people might want to use apart from the app being part of a tutorial. I haven’t found anything to do this well.
Example of this type of app are GraphQL Weekly (built with Gatsby and Netlify) and the CooperPress family of newsletters built in-house on Rails.
Newsletter App Structure
Following are different pieces of the app, in no particular order (and probably missing a few):
-
List and item frontend views of archived newsletters.
-
Subscription and search widgets using Netlify Forms.
-
Topic idea submission widget and associated lambda handler.
-
Admin screens for archived newsletters, register and login screens, admin user management, and topic idea management.
-
Mock MailChimp server as a lambdified Express server, loaded with static copies of Redwood’s archived newsletters. This could either be in the tutorial app’s
packagesdirectory, or a separate package as a dependency. I think there’s value in including it in the tutorial because some people might not be aware you can do this with Express (or the issues with doing so). -
Update lambda that responds to a MailChimp or other webhook when a new campaign is published. It should pull the newly-published newsletter and update the backend data store with the new newsletter.
From comments that @thedavid made in the original Twitter thread, the app will be written in TypeScript and use Tailwind CSS. I think using React Admin might be a good idea for the admin screens.
Tutorial Organization
The current tutorial to create a blog app is divided into two parts, covering these topics over twenty-five pages:
- Welcome to Redwood - Prerequisites - Installation & Starting Development - Redwood File Structure
- Our First Page - A Second Page and a Link - Layouts
- Getting Dynamic - Cells - Side Quest: How Redwood Works with Data
- Routing Params
- Everyone’s Favorite Thing to Build: Forms - Saving Data
- Administration - Authentication
- Deployment
- Setup Tailwind
- Introduction to Storybook - Our First Story
- Our First Test
- Building a Component the Redwood Way (Comments) - Multiple Comments - Adding Comments to the Schema - Creating a Comment Form
- Role-Based Access Control (RBAC)
The structure of a tutorial for a newsletter app would depend on whether the expectation is that someone works through the blog app tutorial first and thus has some background with Redwood, or launches straight into the newsletter app tutorial as an introduction to Redwood.
I think it makes sense to assume they’ve worked through the blog app tutorial. That way the newsletter app tutorial could focus more on advanced topics that aren’t covered in the blog app tutorial like lambdas and API calls. It would also allow the newsletter app tutorial to be organized around building out functional areas as steps instead of needing to work through introductory topics.
Other
The blog app tutorial steps through using Railway for a cloud database provider and deploying to Netlify. It implies hosting the repo on GitHub but isn’t explicit about it. It also doesn’t touch on any specific code editor for use in the tutorial. I suggest the following for the tutorial app:
-
Mention that Redwood has built-in integrations with VS Code (Redwood IDE extension, recommended extensions). Show some of the things you can do with the
.vscodedirectory in a repo like Redwood-specific tasks and code snippets - so a single page early in the tutorial on setting up an IDE for the project. -
Step through setting the repo up on GitHub. Set up a CI / CD pipeline with workflow files in the
.githubdirectory. -
As a non-tutorial topic, include a deploy button to Netlify on the repo in case people want to use the repo rather than walking through the tutorial with it.
Wrap Up
I’m busy next week (October 25th to 29th), but I have downtime from the 30th to November 7th. That’s about ten days, and I’m happy to use it to try and get a PoC up for a newsletter app.
All input welcome!
