Skip to content

Instantly share code, notes, and snippets.

@LinnJS

LinnJS/README.md

Last active November 28, 2023 03:29
Show Gist options
  • Save LinnJS/20a6e2a9d485f56253cac2bc4d3353d9 to your computer and use it in GitHub Desktop.
Save LinnJS/20a6e2a9d485f56253cac2bc4d3353d9 to your computer and use it in GitHub Desktop.
Download ZIP
Philosophies, Technologies, and Acceptance Criteria
Raw
README.md

Philosophies, Technologies, and Acceptance Criteria

  • Philosophy

    • When building applications I always try to Keep It Super Simple with the least amount of complexities as possible. Just incase use cases do get very complexed I like to make sure our design is as modular as possible so we can be flexible and deal with the complexity in an isolated fashion and to use libraries that have escape hatches out of their patterns just in case we need to overcome a edge case library maintainers did not expect.
    • I always try to keep the patterns as clean and simple as possible so it can be junior developer friendly so people can be productive as early as possible and skill up along the way. I was lucky enough to have an awesome first project so I always try to paying that favor forward.
    • For documentation I always try to write docs that wont have to be updated as we pivot and reference documentation of the libraries we use to demonstrate patterns. This way our docs wont go stale and we will follow the patterns of the libraries for as seamless upgrades as possible
    • Type Safety is necessary to be a good citizen of the internet, I also enjoy sleeping at night. All libraries are hand picked to be end to end type safe to create seamless type safe integrations and leverage libraries as much as possible to write our types so we don't have to do all of the hard work.
    • Headless everything this way we can style things however we want and can theme things for different org very easily. Also gives us control over HTML so we can write features as assessable as possible.
    • Testing is very important in crafting scalable applications but on the frontend 100% test code coverage is usually not the best use of time. We should leverage TypeScript to make robust code, unit test business logic, and end to end test user experiences. This will give us total code coverage while maintaining developer experience, productivity, and most importantly peace of mind cause work life balance is important.

  • Architecture & Technologies

    • NextJS (React framework)
      • NextJS is the most adopted React framework and comes out of the box with optimization tools and APIs over top of the standard web API to give an augmented developer experience and larger set of tools that would otherwise have to be home rolled. I.e. Service workers, image optimization, and routing.
    • Type Safety
      • TypeScript for all the things and try to ensure that all libraries are built with TypeScript as much as possible to create an end to end Type Safe environment. This will enable us as a team to write better code, have less bugs, be more agile in terms of refactor-ability, and write less unit test. I love unit test but we just have to write less and only write them where they matter if we use TypeScript everywhere.
      • Zod to increase developer experience, write more complexed and nuanced types, and best of all we get type inheritance out of the box with no extra work. This means once we define types at the top level of components they will trickle down so we only have to define types where data is entering the application.
    • Authentication
      • Auth will be Okta which is the standard for all internal tools across Paramount/CBSi.
    • TailwindCSS with Material Tailwind (CSS Framework)
      • Tailwind is a utility first CSS framework that will give us a design system language and enable us to share styles more easily across applications via style recipes and components.
      • In order to increase productivity and still have a flexible framework that can evolve over time we can use Material Tailwind. This will allow us to move away from material down the line and create a more custom feel over time without compromising on bootstrap-ability. Material tailwind is mostly utility classes that contain CSS so we can maintain control over our own JavaScript.
      • Tailwind also has open source components and style recipes we can use to get features out the door while also having control of our own design. Tailwind Components, Tailwind Elements, and TailwindUI.
    • Storybook
      • Storybook is a design system development environment this allows packages to have somewhere a shared UI can be developed and tested. Storybook is also great for non-technical users and designers to see 1:1 what components are coded, available, and how they work with all the states mapped out.
      • One of my favorite features about Storybook is it also gives your unit test a mocked state you can test against which yields super readable unit test without mocks clouding up the logic. Also the Storybook use cases map to the unit test 1:1.
      • This will give us a nice place to import/export material-ui so we can use it globally and as we make it our own library it will be a one place update across all applications.
    • React Table (AKA TanStack Table)
      • React table is a headless table utility library that is completely headless that allows for endless flexibility. React Table is now fully end to end types in V8 and has tons of adoption.
      • React Table can do all kinds of complexed data groupings, ranking, filters, cell styles, and pagination.
      • One again this library is completely headless so we can evolve the styles over time and make the design system our own over time to make the best user experience possible.
    • Charts
      • This is still a little undecided for me on a personal level need to work with them to see how the developer experience is for each library

  • Forms

    • React Hook Form is by far my favorite form library. It's composed by all hooks and uses implicit spread objects to wire up inputs in a non-controlled manner. This means no more onChange and onBlur handlers unless we need custom functionality. Also integrates directly with design system for seamless and very copy & paste-able forms. Its also very performant with a small bundle size

  • Alternatives are React Final Form which is nice but a little less well rounded with less escape hatches and also very new. Formik is another alternative but heavily uses HoC which I feel clouds up the code. Formik is also component based and I like to have full headless control over my HTML.

    • Client Data Fetching
      • Right now we are using Apollo GraphQL for all client side queries which I have used in the past with great success.
      • Something to also consider is React Query. React Query was directly inspired by Apollo GraphQL but made to be more flexible, performant, with some extra features built on top. React Query is a server sync library and includes offline support, service worker support, and is used by many open source libraries as the way to fetch data. Libraries that use RQ under the hood are BlitzJS & tRPC.
      • Thread on large apps migrating from Apollo Client to React Query
      • Apollo Client & React Query feature comparison
    • State Management (as little as possible)
      • Zustand is my favorite library for state management but my philosophy has been to always use as little as possible and sync with the server whenever possible. I can see this being used for user management.
      • An alternative is Redux Toolkit I am just over Redux and feel Zustand has a better API.
      • Another alternative is Recoil I just prefer Zustand since its built with TypeScript and integrates nicely to TypeScript libraries
    • Workflow Management
      • If we need workflow management down the line we can use XState if we want to do this on the client side or Temporal if we want to do workflow management on the server node side.
      • Not sure if we will need this at all but if we have complicated workflows where certain things need to happen in a certain order this these are both great ways to handle complexed long running workflows.
    • Testing libraries

  • Acceptance Criteria for MVP

    • Create a component library using Storybook and Material Tailwind so we can easily share this code across more than one application
      • As a long term goal would be really cool to popularize our component library to use internally across other react applications.
      • We can also abstract styles and spread them over different elements to support native applications if business value permitted I.e. export both web and native versions of our library
    • Read - Create table that can read all Live Event streams
    • Create - Create a button to add more Live Event streams
    • Update - Add a menu button on Live Event stream to edit the event
    • Delete - Add delete button to remove stream

  • Future enchantments

    • Add button so users can add event groups in tables so they can quickly access the groups they work on most frequently. Could be grouped by org, ids, event types, event locations, or event time slots.
    • Add simple metric tiles to show single stats using a chip and diff calculation
    • Add metric charts so we can monitor the streams over time and get a snapshot on how the streams are doing over historical data
    • Add reports page so user can enter custom query and see reports on performance, engagement, and any other factors that our API will permit. This would be an easier and less technical version of Cloud watch queries
    • Make dashboard customizable and move some features to their own pages so user can make a custom dashboard that fits their unique use case.

Conclusion

These are just my first thoughts and first choices in technology open to any alternitives and discussion around any of the topics above. Feel free to comment and give feedback or ask questions. More any willing to give anything new a try! 😃

I am trying to get a proof of concept up as soon as possible so you call can see what it might look like and play with it a bit. 🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment