"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; function _createMdxContent(props) { const _components = { a: "a", code: "code", h2: "h2", li: "li", p: "p", pre: "pre", ul: "ul", ...props.components }; return _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: [_jsx(_components.a, { href: "https://twitter.com/kylemathews", children: "Kyle Mathews" }), " had the idea to use a custom React reconciler to actually\nrender a recipe in order to \"interpret\" it. This was so mind melting to me, but was something we decided\nto leave for a future exploration when shipping the MVP."] }), "\n", _jsx(_components.p, { children: "Our current implementation (as of May 8, 2020) parses out a recipe using MDX and used the AST to create a set of\ninstructions. This got us pretty far with any resources that are on disk or are flat in nature. Light and\nsimple." }), "\n", _jsx(_components.p, { children: "It worked greatly for adding a Gatsby plugin, manipulating the package.json, or even installing packages\nfrom npm. However, this started to break down when we needed to work with remote resources." }), "\n", _jsx(_components.p, { children: "When I began with remote resources I initially decided to target GitHub and Contentful. Both have powerful\nAPIs, yet are on different ends of the spectrum in terms of what they do. One being a git host with a large\nsurrounding feature set (and a GraphQL API), the other a headless CMS (with a powerful client library)." }), "\n", _jsxs(_components.p, { children: ["Writing the resources themselves for two providers (GitHub and Contentful) was a breeze since the resources\nthemselves implement a simple CRUD interface that's a thin wrapper around an existing library. For example,\nhere's a GitHub repository create (called with ", _jsx(_components.code, { children: "" }), "):"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "const create = async (_context, { name, visibility }) => {\n const result = await client(\n `\n mutation($name: String!, $visibility: RepositoryVisibility!) {\n createRepository(input: { name: $name, visibility: $visibility }) {\n repository {\n name\n url\n }\n }\n }\n `,\n {\n name,\n visibility\n }\n )\n\n const { repository } = result.createRepository\n\n return {\n ...repository,\n id: name,\n _message: message(repository)\n }\n}\n" }) }), "\n", _jsx(_components.p, { children: "Turns out we'd need the reconciler sooner than later. Remote resources quickly made it apparent that\nnesting/composition was a preferable DX because a lot of resources have a natural parent/child relationship." }), "\n", _jsx(_components.p, { children: "For example, consider a resource to create a Contentful space with a blog post content type. Right off the\nbat you end up needing to create a space, which in turn needs an environment (prod vs staging), which is\nthen where you can apply your content type." }), "\n", _jsx(_components.p, { children: "Without nesting, while still being declarative and idempotent, you end up with interdependent props that\nleak the parent/child relationship in a peculiar way." }), "\n", _jsx(_components.p, { children: "Below is a first pass at what that would look like:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mdx", children: "# Contentful blog setup\n\n---\n\nCreate a new space\n\n\n\n---\n\nCreate an environment\n\n\n\n---\n\nCreate the BlogPost type.\n\n\n" }) }), "\n", _jsx(_components.p, { children: "It's not terrible, but it isn't great either. The props interlinking isn't ergonomic and is extremely error prone. Ideally, an API should look something like:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mdx", children: "\n \n \n \n\n" }) }), "\n", _jsx(_components.p, { children: "It's still declarative, more delightful to write, less error prone, and naturally/ergonomically expresses parent/child relationships." }), "\n", _jsx(_components.p, { children: "There's another hidden benefit, too. Right now, since we're using static analysis, it'd be difficult to support other niceties that MDX offers like variable support which can be used to clean up Recipes JSX. With a React reconciler-based implementation we could, for example, create a type that we share between multiple Contentful environments." }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mdx", children: "export const blogPostType = `\n type BlogPost {\n title: String!\n date: Date!\n body: String!\n }\n`\n\n\n \n \n \n \n \n \n\n" }) }), "\n", _jsx(_components.p, { children: "Here's another example for a Github repo configuration:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mdx", children: "export const labels = [\n { color: 'tomato', description: '1' },\n { color: 'tomato', description: '2' },\n { color: 'tomato', description: '3' },\n { color: 'tomato', description: '4' }\n]\n\nexport const projectColumns = [\n 'backlog',\n 'up next',\n 'in progress',\n 'in review',\n 'done'\n]\n\n\n \n {projectColumns.map((col) => (\n \n ))}\n \n {labels.map((label) => (\n \n ))}\n\n" }) }), "\n", _jsx(_components.p, { children: "This also brings out interesting implications for resource API signatures. When we create a Contentful content type we have the following arguments:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "contentfulContentType.create(context, { schema })\n" }) }), "\n", _jsxs(_components.p, { children: ["With the unnested API, we also need to expose the ", _jsx(_components.code, { children: "spaceName" }), " and ", _jsx(_components.code, { children: "environmentName" }), " which actually leads us to end up with:"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "contentfulContentType.create(context, { schema, spaceName, environmentName })\n" }) }), "\n", _jsx(_components.p, { children: "This is peculiar because the parent/child relationship forces us to expose even the grandparent name. Though, in essence, this is contextual information. It can also be addressed with a state file, which we also plan on implementing, but the ergonomics are still a bit off." }), "\n", _jsx(_components.p, { children: "When we revisit the React reconciler idea again, this contextual information is ergonomically exposed with a built-in feature: React context." }), "\n", _jsx(_components.p, { children: "Each step in the composition can expose its context that the children can access in order to handle their processing. Hypothetically, it could look something similar to:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "const space = spaceResource.read(context, props.name)\n\nreturn (\n \n {children}\n \n" }) }), "\n", _jsx(_components.p, { children: "Then, the content type implementation might look something like:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "const context = useContentful()\nconst contentType = contentTypeResource.read(context, props)\n" }) }), "\n", _jsx(_components.p, { children: "This reconciler idea becomes even more interesting, too, because it turns the interpreter into something that can better handle conditional logic." }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "if (someCondition) {\n return \n} else {\n return \n}\n" }) }), "\n", _jsx(_components.p, { children: "The API for the recipes internals would be pretty clean when compared to how it currently works. Hypothetically, plan vs apply modes can be toggled on and off, too." }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-js", children: "ReactRecipes.render(, statefile)\n" }) }), "\n", _jsx(_components.p, { children: "In addition to remote resources, Kyle brought up another architectural benefit that's pretty interesting. When inputs are missing we can \"suspend\" and prompt the user for missing details, env vars, etc. Since we already plan on supporting user inputs soon, this will be a 2 for 1!" }), "\n", _jsx(_components.p, { children: "We've got time set aside next week to explore this custom React reconciler, excited to see where it can potentially go." }), "\n", _jsx(_components.h2, { id: "related", children: _jsx(_components.a, { href: "#related", children: "Related" }) }), "\n", _jsxs(_components.ul, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "https://www.youtube.com/watch?v=CGpMlWVcHok", children: "Building a Custom React Renderer by Sophie Alpert" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "https://github.com/vadimdemedes/ink", children: "https://github.com/vadimdemedes/ink" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "https://github.com/maxchehab/phelia", children: "https://github.com/maxchehab/phelia" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "https://github.com/react-spring/react-three-fiber", children: "https://github.com/react-spring/react-three-fiber" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "https://github.com/diegomura/react-pdf", children: "https://github.com/diegomura/react-pdf" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "https://github.com/chentsulin/awesome-react-renderer", children: "https://github.com/chentsulin/awesome-react-renderer" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "https://github.com/airbnb/react-sketchapp", children: "https://github.com/airbnb/react-sketchapp" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.a, { href: "https://www.youtube.com/watch?v=oPofnLZZTwQ", children: "https://www.youtube.com/watch?v=oPofnLZZTwQ" }) }), "\n"] })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = props.components || ({}); return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { default: MDXContent };

Recipes interpreter with a custom React reconciler