Company Framework

[coryhouse]

Company Framework

Goal: A standardized React development approach for your company.

Current Status

• How many React projects exist?
• How do you start new projects today?
• What are your pain points?
• What comes up often in code reviews?
• What fragmentation exists currently?

Why?

• Programmatically enforce consistency
• Speed code reviews
• Foster cross-team collaboration
• Ease ongoing maintenance
• Centralizes bug fixes
• Centralize updates and coordination among versions of dozens of packages
• Avoid ongoing decision fatigue
• Avoid reimplementation overhead
• Systematize corporate knowledge
• Automate best practices - make doing the right thing the easy thing
• Create a common foundation upon which to run reusable components
• More here.

Decisions

• Boilerplate or framework
• Start from scratch or utilize create-react-app?
  • Fork or create custom react-scripts viareact-app-rewired
  • Can override Babel and ESLint too via customize-cra
• Editor
  • Which one?
  • Which extensions/plugins?
  • Suggest plugins in VSCode
  • Review my suggested plugins. Other React codegen option
  • Use built in terminal?
• HTML generation
  • Minify?
  • Use plugin?
  • Inject prod only concerns?
  • Templating language?
• What belongs in each component folder?
  • Component, with name matching folder
  • index.js (barrel pattern) or package.json with main set to component
  • stylesheet? Named after component?
  • test
  • Use Lego "brick" approach from eBay? (see patterns)
• Keep dependencies updated via dependabot (free and built into GitHub) or more full-featured services like greenkeeper.io, or renovate. Renovate is most configurable.
• Declare and export design tokens in multiple formats (CSS variables, SASS variables, JSON export, JS export). Useful for colors, spacing, font sizes, etc)

Transpiling

• Babel
• TypeScript
  • Alternative: Enable TypeScript checking on plain JS in VS Code
• Flow
• PropTypes
• Use experimental features?
• Which plugins?
• Production vs dev config
• Handling immutable data

Bundler

• Webpack, Browserify, Parcel, Rollup…

Linting

• Which linter?
• Warnings, errors, or both?
• Publish your own linting plugin
• Select plugins
  • eslint-plugin-import
  • eslint-plugin-jsx-a11y
  • eslint-plugin-lean-imports
  • Lint testing files too via eslint-plugin-jest?
• Select settings
  • Start from recommended, existing plugin, or from scratch?
  • Forbid some imports?
  • Enforce style, or use Prettier or editorconfig?
• Run lint and prettier on commit via husky?
• Enable which rules?
• Use a preset?

Testing

• Framework?
• Assertion Library?
• Helpers?
• Test file location? Alongside or under /test?
• File naming?
• What environment?
• Mocking?
• Code Coverage
• Continuous Integration
• When to run tests
• Test for forbidden dependencies. Here is an example. Your base bundle needs to depend on the routes, because when you go from A to B, you need to already know the route for B, so it has to always be around. But what you really don’t want in the base bundle is any form of UI code, because depending on how a user enters your app, there might be different UI. So, for example the date picker should absolutely not be in your base bundle, and neither should the checkout flow. Assert that the base bundle doesn't contain any libraries that can be lazy loaded. Avoid centralized dependencies. Instead, use the enhance pattern and generate code. Here's how: files can declare what they want to enhance and a code generator can find these files and generate the centralized file. Example: Put a "decorator" (e.g. ##ROUTEME##) in a file to mark it as relevant to the router. This avoids a centralized dependency, and when you want to delete the file, you can do so without touching some huge centralized file. This also makes it easy to delete code, which is what we should optimize for.

Project structure

• Organize files by file type or feature?
• Centralize API?
• Allow Inline JS?
• Extract to utils (POJOs)?

HTTP

• Library
• Mock schema format
• Mock data generation
• Mock server

Production build

• Minification
• Sourcemaps
• Bundle splitting
• Cache busting
• Error logging
• Automated Deployment to your preferred host
• Error logging

Styling

• Styling tech
• Stylelint
• Host styles on CDN

API Calls

• REST vs GraphQL
• Library
• Centralized file location
• Publish and bundle proxies?
• Mock API
• Suggest editor plugins via VSCode
• Bundler
• Automated File Generation via templates plop, Hygen
• CLI vs Git clone

Monorepo

• Convince a few consumers to place their project within your monorepo. Why?
  • Truly continuous integration = instant feedback on breaking changes
  • White glove handling of breaking changes
  • Easily test new ideas in a real world environment
  • Consider setting up CI to run for consuming projects when you publish betas. Walmart does this. This way you know when you've broken other projects.
• Unified versioning?
• Lerna
• Yarn workspaces
  • Related projects to consider bundling in monorepo
    • Reusable components
    • App Starter
    • Component Starter
    • API Wrapper
• Demo app
  • Show examples of file naming, locations, validation, folder structure, Redux configuration, performance approaches.
  • Highlight key features
  • Make it easy to remove

Documentation

• Branding
• Compose with style guide?
• README.md
  • Why does this exist?
  • How do I report issues?
  • Who is using this?
  • How do I get started?
• CONTRIBUTION.md

Release process

• Semantic versioning
• Release notes
• Publicize via Slack, email. Collect emails of users.