Ryan O'Shea

Concept and Design

---

The objective of this project was to create an app where a team working on software could log, assign, organise and track the progress of issues, and analyse the performance of the team.

The app is currently freely available to install on organisations' servers by downloading the source code from Github. An online version for organisations will be available soon. The current online version is not suitable for use by different organisations and is only intended for demonstration.

The project team decided to use Trello to track the development. Available here: Bug Twitter Trello

The first step was to create user personas. These were based on the project team's working experience. These personas were used to develop user stories which in turn became user flow diagrams.

The project team realised that user flow development was an important step they had missed in earlier projects. It gave them clear guidance to turn diagrams into wire frames.

Since the scale of the project was small and communication between stakeholders was very informal, the development team decided to use paper and pencil to prototype the app.

The team decided on a mobile first approach.

At this point the team became blocked due to lack of experience in UI design. A breakthrough was achieved when the team decided to borrow liberally from an existing app: Twitter.

By adapting the design to suit their needs the team were able to move to development.

Next.js was chosen as a framework since it was familiar to the team, has great documentation, allows rapid front and backend development in a monorepo.

This choice informed how the wireframes were broken into components: firstly as pages, layouts and then as shared components.

The components were each given a brief specification before any code was written.

For authentication NextAuth.js was chosen. This was a new library for the team. Mongo and mongoose would be the ORM and database. This was chosen due to familiarity. The team would also write tests for the first time.

Development

---

No plan of operations extends with certainty beyond the first encounter with the enemy's main strength.
— Helmuth von Moltke the Elder

The clock was ticking. The team was now well into the allotted time for completing the project. After the initial commits, setting up the database, testing, and other tools, the team wanted to implement authentication and authorisation.

This was initialised successfully but the team's gaps in knowledge and understanding slowed progress. The successful implementation of authentication was critical part of the project. And the team were not confident that they would be able to realise that within the time frame.

Blitz.js is described as a batteries included Javascript framework. It is based on nextjs but comes with extra features:

• a Mysql-lite database
• an ORM - Prisma
• Jest or React Testing Library (RTL)
• Formik or React Final Form (RFF)
• React Query
• a zero api layer¹
• authentication

Switching the choice of development stack would give the project what it needed, authentication, but there would be a the risk of adopting unfamiliar tools from a relatively new project.

The team took 2 days to review the material on Blitz and try out a short demo app.

We decided to move forward with Blitz.

With Blitz our way forward was clear but we expected challenges. We also decided to use Typescript for the first time and leave testing for another project.

Typescript gave us some of the hardest errors that the team has ever had to fix. Those errors plus all the clutter of angle brackets for React Typescript props made the team doubt its decision. But still we fixed the bugs and got used to the syntax.

However, using React Final Form with Chakra-UI and Typescript was an even greater challenge that needed direct support from RFF's creator and other community members. This was our biggest point of development pain.

Prisma and the Blitz.js zero api layer made writing CRUD functions for users, issues, projects and teams far easier than any library the team has used until now. Prisma has excellent documentation and is definitely in the "will use again" category.

The project eventually overran by many weeks. Towards the end of the initial phase the team realised that meeting the deadline of December 7th was unlikely. Work was rearranged to ensure a more sustainable pace into the second phase.

At the moment of writing BugTwitter is a functioning issue tracker but still needs some most important features: refactor to support organisations through multi tenant architecture, comments for issues, and additional UI development.

Conclusion and Learning Outcomes

---

Full disclosure: the team has one developer, me.

The purpose of this project is to go through the steps needed to design and develop an application using an uptodate JS developer stack using React and Next.js.

Producing something new and innovative for the market was not the goal. I wanted the experience of completing a set of tasks that would give me insights and points to work on for future more innovative projects.

Thanks for reading and here are my key conclusions:

1. Expect the unexpected

Blitz.js seemed like it was moving towards a stable release. It is a project that I had been following for a while (maybe as far back as 2019). Even as an entry level developer, who had just heard of Next.js, it made perfect sense to develop a framework based on Next that everything needed to bootstrap a fullstack app.

The announcement from the creator of Blitz, Brandon Bayer, that he was pivoting the project due to lack of traction was a little open source lesson for me. I had a great experience using Blitz and the lessons I can certainly use in any Next.js app.

But if I were a more vulnerable personality this might have made me throw my dev dummy out of the pram. Thankfully, my perspective keeps me focused on finishing the project and not getting freaked out by OSS tower moments.

2. Compare docs

I had choice between Formik and React Final Form. I went with RFF as it was recommended by the Blitz in their docs, and has a smaller bundle size. This was an error that cost me days of progress.

I found the RFF community on Discord very helpful but the docs drove me to despair and desperation. This was my error and I certainly don't want to my experience to be a criticism of what the creator and the community has produced. But I certainly learned a lesson.

3. Prisma

I really like the simplicity of the schema file; the way to prototype the database using prisma push; the simplicity of making changes to the database using prisma migrate; the visualiser; and the docs... man, do I love their docs. And their community. And that they are in my neighbourhood in Berlin.

4. Prisma, the Blitz zero API layer and tRPC

I'm a bit shy about using Blitz again but the DX of calling queries and mutation to read and write to the database is very seductive. There is a project called tRPC with offers a similar API. I'll most likely want to try that out in my next project.

5. Document the process regularly

This was a missed opportunity. I'm still finding my developer's voice. Which is probably more Gonzo in tone and more about the DX.

6. Make more apps

It really ain't rocket science (at least not in terms of the risk of catastrophic failure).

The key to learning software development really is doing software development.

Maybe I'll do another post on what learning by doing has meant to me in my working life and how it works. It is easy to throw the term at a learning problem but understanding it heuristically and theoretically could be useful and fun to write about.

7. Make more UIs

UI's are a funny one for me. I studied design. I have an eye for layout in documents, posters, flyers and the like, but until now most of my projects don't have much or any visual charm.

This was the first project where thinking about the look and feel didn't seem like too much of a stretch. But what is missing is the raw experience in making UIs. More of that needed.

8. Keep using Typescript

Stockholm syndrome has set in.

9. Test another day

There was just too much mental overhead at the beginning of the project to write tests for the first time. I needed to get properly working on a project and open up the space in my imagination for tests. But I can certainly see how tests benefit app development.