DEV Community: Michał Pietraszko

How To Structure Your App In a Way That Scales.

Michał Pietraszko — Sun, 27 Jun 2021 19:50:07 +0000

The best codebases I found myself working on had their folders structured around the features the app provides.

Some folks might tell that it is very close to the Domain-Driven Design's principle of bounded contexts.

The App We Will Structure

Thinking of application as a feature that contains features creates a robust mental model that can be easily mapped to the folder structure of your project.

The following example will refer to a Single-Page Application written in JavaScript that consists of the following building blocks:

Routes - root components displayed when an URL is used,
Components - logical units handling state and rendering,
Queries - functions calling an HTTP API,
Styles - CSS bound to the specific component they are named after,
Services - logical units handling overarching problems

Remember, this pattern can be applied to any programming language, framework, and problem domain.

For example, a game could use shaders, prefabs, entities, and systems as its own building blocks instead.

My goal here is to present the idea in an easy-to-digest way. For this reason, I'll make a few simplifications when we go through the evolutionary steps.

The Genesis

Our app will start with login and register features.

It should be able to take input data and communicate with the API.

When a user is logged in, then they will be able to see some kind of message that they have an active session.

The simplest way to start is with one file. From this point, we will take a few steps.

src/
├─ index.js
├─ style.css

The features are apparent when someone opens the index.js file.

The Buckets

Now, imagine the business wants the app to do more. They say, that after the user logs in, they should see the dashboard with charts representing important data.

You start writing code and at one point the sense of guilt ensues... the index.js file became too large and you think that as a good engineer you should organize your code better.

Usually, people organize the code in what I like to refer to as buckets and end up with something like this.

src/
├─ services/
│  ├─ session.service.js
├─ components/
│  ├─ button.component.js
│  ├─ input.component.js
│  ├─ piechart.component.js
│  ├─ linechart.component.js
├─ routes/
│  ├─ login.route.js
│  ├─ register.route.js
│  ├─ dashboard.route.js
├─ styles/
│  ├─ input.component.css
│  ├─ button.component.css
│  ├─ piechart.component.css
│  ├─ linechart.component.css
│  ├─ dashboard.route.css
│  ├─ login.route.css
│  ├─ register.route.css
├─ queries/
│  ├─ login.query.js
│  ├─ register.query.js
│  ├─ dashboard.query.js
├─ index.js
├─ style.css

Is there an objective problem, at this point, with this? No. Things might feel alright because every concept has its own bucket. There is not much functionality, but as it grows - your feelings might change.

More Features

Now, the business says that we should add some reports that will allow users to see critical information - for example, how much money they've gained and how much money they've lost. These are expected to include tabular data and charts.

Let's add more to the buckets.

src/
├─ services/
│  ├─ session.service.js
├─ components/
│  ├─ button.component.js
│  ├─ input.component.js
│  ├─ data-table.component.js
│  ├─ piechart.component.js
│  ├─ linechart.component.js
│  ├─ barchart.component.js
├─ routes/
│  ├─ login.route.js
│  ├─ register.route.js
│  ├─ dashboard.route.js
│  ├─ loses-report.route.js
│  ├─ gains-report.route.js
├─ styles/
│  ├─ input.component.css
│  ├─ button.component.css
│  ├─ data-table.component.css
│  ├─ piechart.component.css
│  ├─ linechart.component.css
│  ├─ barchart.component.css
│  ├─ dashboard.route.css
│  ├─ login.route.css
│  ├─ register.route.css
│  ├─ loses-report.route.css
│  ├─ gains-report.route.css
├─ queries/
│  ├─ login.query.js
│  ├─ register.query.js
│  ├─ dashboard.query.js
│  ├─ gains-report.query.js
│  ├─ loses-report.query.js
├─ index.js
├─ style.css

That's a lot of files scattered around.

Ask yourself the following questions.

Is it immediately obvious to you what features the app consists of?

Is it clear what features are dependent on each other?

Feature-driven Folder Structure

Let's take a step back and write down what features and areas of concern the app covers.

Login
- Receives data input
- Cares about current session
Registration
- Receives data input
- Cares about current session
Dashboard
- Visualization via charts
- Cares about current session
Loses Reporting
- Visualization via data table
- Visualization via charts
- Cares about current session
Gains Reporting
- Visualization via data table
- Visualization via charts
- Cares about current session

Think about the whole app as a feature.

Also, think about each bullet point as a separate feature.

Each feature is specialized in one problem domain.

Some features are shared between features.

Let's map this to the folder structure.

Please keep in mind that structure might differ depending on a person and the team working on the codebase!

src/
├─ shared/
│  ├─ session/
│  │  ├─ session.service.js
│  ├─ data-table/
│  │  ├─ data-table.component.js
│  │  ├─ data-table.component.css
│  ├─ data-input/
│  │  ├─ button.component.js
│  │  ├─ button.component.css/
│  │  ├─ input.component.js/
│  │  ├─ input.component.css
│  ├─ charts/
│  │  ├─ piechart.component.js
│  │  ├─ piechart.component.css
│  │  ├─ linechart.component.js
│  │  ├─ linechart.component.css
│  │  ├─ barchart.component.js
│  │  ├─ barchart.component.css
├─ login/
│  ├─ login.route.js
│  ├─ login.route.css
│  ├─ login.query.js
├─ register/
│  ├─ register.route.js
│  ├─ register.route.css
│  ├─ register.service.js
│  ├─ register.query.js
├─ dashboard/
│  ├─ dashboard.route.js
│  ├─ dashboard.route.css
│  ├─ dashboard.query.js
├─ gains-report/
│  ├─ gains-report.route.js
│  ├─ gains-report.route.css
│  ├─ gains-report.query.js
├─ loses-report/
│  ├─ loses-report.route.js
│  ├─ loses-report.route.css
│  ├─ loses-report.query.js
├─ style.css
├─ index.js

Ask yourself the following questions, again.

Is it immediately obvious to you what features the app consists of?

Is it clear what features are dependent on each other?

From my experience, a developer can immediately tell what features the app has and where they have to go if they have the task of modifying the code.

Feature of Features... of Features?

The problem I've experienced when applying this pattern was the shared program expanding to unmanageable size creating a similar problem to "the buckets" approach.

There is one trick to deal with this.

Take a look at the structure above and try to tell what shared features are not related to everything?

...

The charts and *data table features.

The important thing to remember is that the feature-driven pattern has no limit to how deep the structure can go.

It should go as deep or as flat to ensure comfort which is subjective.

Check the following example of how the structure can be made to represent the relationship between features even better.

src/
├─ shared/
│  ├─ session/
│  │  ├─ session.service.js
│  ├─ data-input/
│  │  ├─ button.component.js
│  │  ├─ button.component.css/
│  │  ├─ input.component.js/
│  │  ├─ input.component.css
├─ login/
│  ├─ login.route.js
│  ├─ login.route.css
│  ├─ login.query.js
├─ register/
│  ├─ register.route.js
│  ├─ register.route.css
│  ├─ register.service.js
│  ├─ register.query.js
├─ reporting/ 
│  ├─ data-table/
│  │  ├─ data-table.component.js
│  │  ├─ data-table.component.css
│  ├─ charts/
│  │  ├─ piechart.component.js
│  │  ├─ piechart.component.css
│  │  ├─ linechart.component.js
│  │  ├─ linechart.component.css
│  │  ├─ barchart.component.js
│  │  ├─ barchart.component.css
│  ├─ dashboard/
│  │  ├─ dashboard.route.js
│  │  ├─ dashboard.route.css
│  │  ├─ dashboard.query.js
│  ├─ gains-report/
│  │  ├─ gains-report.route.js
│  │  ├─ gains-report.route.css
│  │  ├─ gains-report.query.js
│  ├─ loses-report/
│  │  ├─ loses-report.route.js
│  │  ├─ loses-report.route.css
│  │  ├─ loses-report.query.js
├─ style.css
├─ index.js

Now, when you traverse the codebase, you can clearly see what you are looking at and what are the dependencies that you take into consideration.

This way you can add as many features as you need and the structural complexity should be proportional to the actual problem the app tries to solve.

Final Words

Keep in mind that there is a lot of space when it comes to organizing code in a feature-driven way and people can come up with different structures.

There is no objectively correct structure.

You can also mix "the bucket" and feature-driven approaches.

This is because sometimes it might be easier for the eyes to just put shared single components into components folder to avoid many single file folders.

The important thing is to define your own rules of thumb and stick to them.

You can always reflect back and refactor the structure as the codebase evolves.

React Hooks Factories

Michał Pietraszko — Sun, 07 Mar 2021 14:38:45 +0000

Factory pattern with React Hooks is not mentioned often enough however, it is often used in popular libraries to push composition to its limits.

It can also be used to simplify, in some cases optimise, sharing state across the React app.

Factory Pattern Crash Course

Factory pattern is used to bring an ability to create objects on the runtime.

It usually looks like this. Bear in mind that these are simple examples to paint a picture.

interface User {
  name: string
}

class Factory {
  public static getUser(name: string): User {
    return { name }
  }
}

const user = Factory.getUser("Bob") // { name: "Bob" }

// Alternatively, without classes

function getUser(name: string): User {
  return { name }
}

const user = getUser("Bob") // { name: "Bob" }

First Hook Factory

It will be a custom hook wrapping useState but it will set a default value provided at the time of creation.

// Factory function that returns a new function that uses Hooks API.
function createHook(initialValue: string) {
  return function useHook() {
    return React.useState(initialValue)
  }
}

// Create the hook.
const useHook = createHook("some initial value")

// Use the hook in the component.
// The component will output: "State is: some initial value"
function Component() {
  const [state] = useHook()
  return (
    <>
      State is: <b>{state}</b>
    </>
  )
}

Hook Factory With Custom Logic

Factories unlock the next level of composition.
For example, a factory can produce a hook that can be given custom logic at the time of creation.

// Factory function that returns a new function that uses Hooks API.
function createMappedState(mapper: (value: string) => string) {
  return function useHook(initialValue: string) {
    const [state, setState] = React.useState(mapper(initialValue))

    // Define a custom setter applying custom logic.
    const setter = React.useCallback(
      (value: string) => {
        setState(mapper(value))
      },
      [setState]
    )

    // return a tuple to make API similar to React.useState
    return [state, setter]
  }
}

// You can create as many custom hooks you need
const useUppercasedString = createMappedState(value => value.toUpperCase())
const useLowercasedString = createMappedState(value => value.toLowerCase())

// Use the hook in the component.
// The component will output:
// `
// String is: SOME VALUE
// String is: some value
// `
function Component() {
  const [string1, setString1] = useUppercasedString("Some Value")
  const [string2, setString2] = useLowercasedString("Some Value")
  return (
    <>
      String1 is: <b>{string1}</b>
      <br />
      String2 is: <b>{string2}</b>
    </>
  )
}

Sharing state across hooks to create context without Context API

Factories get interesting when you realize that the new function has access to the scope of the factory.

function createSharedStateHook(initialValue: string) {
  let sharedValue = initialValue

  // An array in a shared scope.
  // Produced hook will always refer to it.
  const stateSetters: ((v: string) => void)[] = []

  // This function will update all components
  // that use the hook created by the factory.
  function setAllStates(value: string) {
    sharedValue = value
    stateSetters.forEach(set => {
      set(value)
    })
  }

  return function useSharedState(): [string, (v: string) => void] {
    const [state, setState] = React.useState(sharedValue)

    React.useEffect(() => {
      // On mount, add the setter to shared array.
      const length = stateSetters.push(setState)
      const index = length - 1
      return () => {
        // On unmount, remove the setter.
        stateSetters.splice(index, 1)
      }
    }, [setState])

    // The trick is to have the hook to return the same instance of `setAllStates`
    // at all times so the update will propagate through all components using the produced hook.
    return [state, setAllStates]
  }
}

const useSharedState = createSharedStateHook("initial")
const useAnotherSharedState = createSharedStateHook("another initial")

// `useSharedState` and `useAnotherSharedState` do not share the same state
// because returned hooks have access to different scopes.

function Component() {
  const [sharedState] = useSharedState()
  return (
    <>
      Shared state is: <b>{sharedState}</b>
    </>
  )
}

function AnotherComponent() {
  const [sharedState] = useAnotherSharedState()
  return (
    <>
      Another shared state is: <b>{sharedState}</b>
    </>
  )
}

function Modifier() {
  const [sharedState, setSharedState] = useSharedState()
  return (
    <input
      type="text"
      value={sharedState}
      onChange={e => setSharedState(e.target.value)}
    />
  )
}

function App() {
  return (
    <>
      <Component />
      <br />
      <AnotherComponent />
      <br />
      <Component />
      <br />
      <Modifier />
    </>
  )
}

Now, this hook provides a shared state without having to wrap an app with a Context Provider.

Not having to wrap a large section of the tree brings an alternative way to optimise re-renders without having to resort to more advanced APIs.

Who Is Using This Pattern?

Material-UI's makeStyles function allows to create styles for specific components.

use-local-storage-state - the prime example that inspired me to write this blog post.

In Conclusion

React Hooks are a great way to compose functionality in the ecosystem. Adding a factory pattern on top of it opens the door to more interesting ways to solve problems beyond stitching hooks together.

Web apps are too complex. This is how we can simplify them.

Michał Pietraszko — Sun, 10 Jan 2021 19:54:32 +0000

I believe that we can do a better job of managing the complexity of our apps.

Not many of us realize how many second-order effects our decisions have caused.

Let's see how complexity had grown over time.

The Static era

Simple times. We had a MySQL database, business logic and HTML + CSS views.

All content was static, the browser's job was to display content, navigate and submit forms.

I like to think about test effort as a benchmark for simplicity. There were 3 layers.

Business logic and persistence layer can be easily integrated and view layer can be browser tested.

You may need a tester, developer, and a designer to maintain something like this. It is realistic to have one person responsible for all of this.

The AJAX era

JavaScript opened a door for more considerations in user experience. Adding a dynamic menu, forms, or calendar to a WordPress website was the coolest thing you could do.

We have a complexity spike on the client-side.

Many browsers differed in JS implementation, which required jQuery to come into existence.

This gave a lot of power to designers and has moved more engineering effort into the front end. JavaScript made the browser extensible.

Did the testing complexity increase? Yes. Each new JavaScript bit could only be tested in a browser.

This requires testing, backend programming, JavaScript, and design expertise in your team. Jumping between server-side and client-side languages became frustrating. There was a trend to have different people responsible for each side.

The Single-page era

Remember the first example of the Angular.js app? The input field that automatically updated the content of the div? Good times.

Welcome to the single-page era where front-end development became even more complex than back-end development - mostly due to relevant logic moving to the client. As a result, the divide has increased and JavaScript fatigue became a thing.

We have ended up with two apps that are tightly coupled.

To maintain this, you need at least someone experienced in testing, backend, frontend development (extensive framework, tooling, and browser knowledge), and design.

Now, two apps have to be maintained, and there is much more code than ever. You have to maintain unit, integration, and end to end tests on both sides. Now business logic is not directly accessible due to security concerns.
Frontend and backend now have to maintain layers that are responsible for communication.

Client code needs lots of API mocks to be tested on lower levels - DOM tests are resource-heavy.

Orchestration becomes difficult because you have to make sure that deployments are synchronized. It is even more difficult if you have separate teams for the backend and frontend.

Don't forget about browser testing that also can have a lot of overlap with client-side integration tests. Even more, things to consider in terms of complexity and trade-offs.

That resulted in more code, which contributed to - again - increased complexity.

SEO became problematic, but thankfully this problem has been addressed by the ecosystem through server-side rendering and hydration.

Good patterns have emerged too. UX became better and more creative. We are finally capable of defining client-side logic in a manageable and scalable way.

We all know now that we want to have components and avoid excessive side effects, together with uncontrollable state mutation.

React de facto became a standard.

Simplicity renaissance

The remedy to complexity is embracing the coupling and making the developer experience unified.

Simplicity through innovation in older frameworks.

Ruby on Rails and Laravel are relevant.

Consider them. Their maturity will allow you to move very fast.

They have recently innovated in many interesting ways.

Take a look at Laravel's components or RoR's Hotwire!

Next generation of JavaScript frameworks

People who want to stay in JavaScript land should consider the following.

Next.js started a good trend by putting React and server logic next to each other.

Blitz.js, which is based on Next, is a good ruby on rails equivalent. It brings the right amount of abstraction that makes you treat your app as a unified whole. Using it sometimes feels like cheating - in a good way. It inspired me to talk about the complexity issue in our ecosystem.

Remix with a fresh take on the problem domain and bringing a lot of good and forgotten patterns.

React's Server Components to make everything even better.

Recently, the React team has presented a new idea that can make our component-driven world better.

Consider reading the article and watching their presentation.

When they are released, then we will end up in the best-case scenario where web apps are only dynamic in
places that require it without having to jump between server-side and client-side paradigms.

All of the frameworks above will benefit from them.

In conclusion

We should start asking ourselves if our standard approach is something we still want to maintain.

Suggested frameworks reduce complexity and allow us to experience the simplicity of older approaches while having the benefits of the modern approach.

They embrace the fact that both backend and frontend are tightly coupled and make the developer experience unified.

This is an opportunity to write less code, spend less time testing, simplify orchestration, spend less money on more people having to maintain the complexity, and put more effort into products we are trying to create.

How to post on DEV and still own your content effortlessly.

Michał Pietraszko — Wed, 30 Dec 2020 20:22:03 +0000

DEV is a great platform to start blogging but it doesn't give a straightforward way of owning your content. Some bloggers are asking how to set up a custom domain on DEV which unfortunately is not possible.

What does owning content mean and why would I want to do it?

It means that your content isn't bound to a specific platform.

If DEV becomes irrelevant then for any reason, you shouldn't be affected by it. Your content should accessible no matter what and you are the one deciding what happens to it. Locking yourself to a specific platform will set you back if you want to become independent at one point.

Why to post on DEV if you want to own your content?

The community. You can reach more people if you make your content visible in as many places as possible. Also, DEV enables interaction via comments. Don't forget the SEO it has.

How to post on DEV and still own my content? What is the secret?

Fortunately, there is a way to benefit from posting on DEV and content ownership.

You can achieve it effortlessly by using Netlify with Gatsby Starter Blog and making sure that canonical tags are properly maintained.

Why Gatsby starter blog?

It gives you a very good foundation for a personal blog that is very well optimised. Also, both DEV and Gatsby blog starter use markdown for content creation which boils down maintenance to copying markdown files and adjusting the front matter.

How do I do it?

Before you start.

Create a GitHub account if you don't have one already.

Setting up a personal blog.

Open gatsby blog starter repo which is available here and click on "Deploy to Netlify" button which is at the bottom of the page.

Follow all of the steps and tada 🎉 you have a Gatsby blog!

Buying and setting up a domain

It is not mandatory, but I strongly recommend doing it straight away. You'll avoid the pain of having to move content to a new domain if you decide to set it up later.

Follow the guide from Netlify which you can access here.

Modifying your Gatsby blog.

Pull your repository via your favourite GIT client.

Update siteUrl entry in gatsby-config.js file so it has your domain. This will ensure that all URLs are generated properly.

Delete all files from content/blog directory. You don't need example posts in your blog.

Adding canonical tags to your blog.

Now, the critical part. You have to update the site so it applies a canonical tag for each page.

Without it, Google will punish you for duplicating content.

The canonical tag tells Google which URL is the source.

Gatsby has a plugin for that, follow this guide to implement them.

Writing your content.

What I am doing at the moment is the following:

Write my post on DEV.
Update the front matter with canonical_url. In case of this post it looks like this: canonical_url: https://michalpietraszko.com/how-to-post-on-dev-and-still-own-your-content-effortlessly
Copy the content to a markdown file in my repo. In my case it goes to content/blog/how-to-post-on-dev-and-still-won-your-content-effortlessly/index.md.
Add entries to the front matter that are specific to my blog such as description or date.
Push changes to my repo.
Publish my post on DEV.

Rinse and repeat and enjoy the benefits of owning your content and DEV!

How to make an accurate estimate? You don't.

Michał Pietraszko — Sat, 26 Dec 2020 12:38:13 +0000

A recent popular tweet made me worry because people might agree with it for the wrong reason.

Without calling out people, all of it boils down to this quote:

Don't trust developer estimates.

People saying it and agreeing with it is a sign of the problem. It paints a picture of a developer being a person you cannot trust and makes less experienced folks feel bad.

The issue spans beyond twitter. Many books and engineers talk about it a lot. I bet somebody gave you the advice to double or triple your estimates as a rule of thumb.

Everyone involved in software projects has to stop ignoring the fact that an estimate implies uncertainty.

Dealing with uncertainty.

Reality changes every day. What worked a month ago is not guaranteed to bring the same results this month - especially in the modern world.

What we do carries a risk. We should embrace the fact that we cannot eradicate it and focus on reducing it instead.

If the estimation is uncertain, then it does not reflect reality - be it story points or actual hours. Why would you want to bet on it then?

Focus on the objective. I don't mean finishing user story A, B, and C. Don't confuse it with a task. Think of it more like the outcome you want to reach. You might want to improve conversion in a specific channel, help customers do X, or assess the viability of a technology.

If your measurements had proven that something you do is not working as expected, then it is time to take learnings, apply them, and continue what you are doing or pivot.

Rinse and repeat until you achieve your desired outcome.

Dealing with time.

Time exists, we can't deny that, but estimate still means nothing when it comes to delivering actual value.

I am not saying that you should always take your sweet time. You still have to impose limits on yourself.

Give yourself a time frame for contribution. Be it a two-week sprint goal or a quarterly objective measured by key results.

You still have to take your organization's and team's values into consideration. Some might find unpolished look acceptable. Others might not.

Combining the limits with clear objectives and values can yield results faster. They might not be what you have expected, but it is better to learn about it sooner than later.

Some might say that they need a time estimate so they can put pressure on themselves or their team. More sensible people consider the unpredictable nature of estimation and double, or triple, them just in case.

There is a problem with this mindset. It switches the focus from delivering value to getting specific things done on time. Time spent is not directly proportional to the value.

You don't reduce risk by increasing the estimated time. You are reducing risk by validating your assumptions often instead.

If you are worried about how much time work will take, focus on reducing the friction in your team instead.

What if they still expect you to give an estimate.

If you agree with the organization's reasoning or are willing to accept it, then go for it.

If you are not, then you can try influencing people around you - which is a great skill to learn - and be good friends with them or consider looking for new opportunities.