I remember my first project was a bit daunting in this regard. I was completely lost and was afraid to look unprepared or too incompetent to ask questions.

So, to help you overcome this here is my list of things I usually do when I start on a new project / codebase.

1. 🔎 Assess the project's structure

Regardless of what you are working on, frontend, backend, devops etc in a project you will always have specific file / folder structure. Specific tools being in use to format, lint validate, build, deploy, preview the code etc. There will be specific naming and organisation conventions (or a lack of them).

More often than not, you can study this right at the doorstep of the project. Take a good look at the project's main file containing dependencies (for JS users - package.json for example). Surf through the files and direcotries to understand how features are broke down.

2. 🏎️ Launch the project locally

Regardless if it's a website, a server, plugin or a driver - if you plan to work on it, you will most likely need to build it locally. So, do this then.

Now that you have an idea what kind of tools are being used in the project, second order of the business is to try to run the project locally. It might be as simple as running npm run dev (or alternative command), or might be something more complicated, with different dependencies for different operating systems, installing additional software etc (which you should be aware of from the first step - if not, you will inevitably get hints in forms of errors on what is lacking on your machine).

One thing I find common between different projects - lack of documentation around different environment variables. More often than not you will different environment variables containing some configurations, secrets etc. Sometimes they are not properly documented and the consequences of missing them out when starting the project can sometimes be not very obvious. Keep it in mind.

3. ✍️ A small change

You have a good idea what tools are being used. You launched the project. You feel like nothing can stop you now. Wait. Do not try to conquer the world... just yet.

Start small - take a small request to change (pick an issue, or, if you are in a professional environment, one will be assigned to you most likely) and dig from there.

Here is a very concrete example, you need to change that alert notification text and how much it is displayed on the main page.

Identify potentially static parts of this alert (something that does not change based on X scenario and always remains the same), like a text. Try to find this text inside the project by searching globally over the project. Find the responsible component or a feature that produces this text. Most likely, you will have some logic around it - some timing, some constructors, translations etc.

Even if you cannot find the specific text, take a neighbour text, something that lives pretty close to what you need to change, and search for it. Most likely, you will find them residing side by side.

Pay good attention at why you found this text where you found, how the file is called, why is it being there. What does it interact with and what relies on it. I call it - context scanning. You have a chance to scan the context around something and see how things are working, even if it is just a text and a button.

4. 💅 Check existing / open pull requests

This step can be done outside of the order of these advices as it is more of a "keep your head above the water" advice. It is good to know what your teammates are doing, how do people leave review (identify who is the most mean person in the wild west and get reviews only from them), what kind of features are being prepared and what kind of files are being modified for it to work.

5. 🙋 Ask questions

More often than not, you will have someone to help you and to answer your questions. Sometimes very available person, sometimes not at all or almost not.

In any case, be ready to ask questions. Asking questions about the project, structure, where to start or what might be potentially affected is never a stupid idea. In fact, it is considered as a good thing - you don't want to mess things up. Just make sure you tried to steps above, tried to find the answers yourself. If you feel like it is specific to the project and does not have an obvious and straight forward answer -ask away.

Et voila 🥖

I got those steps by starting on many new projects and it kind of became a habit that I use now on every new project I start on.

Hoping this helps and bon courage!

When using Google OAuth in Wasp project, you might notice that behind the scenes, whenever you are logging in the user, creates the user for you, if it doesn't exist. It does so with very minimal user fields, but what if you need additional user information, such as profile image or full name?

Let's take care of that and learn a thing or two about Wasp lang.

The solution

1. Make sure your database has the correct columns, in the User table. In my case, I added 2 more properties to the User entity, in my main.wasp file:

entity User {=psl
  id                        Int             @id @default(autoincrement())
  email                     String?          @unique
  password                  String?
  isEmailVerified           Boolean         @default(false)
  emailVerificationSentAt   DateTime?
  passwordResetSentAt       DateTime?
    profileImage                            String?
    fullName                                    String?
  stripeId                  String? 
  checkoutSessionId         String?
  hasPaid                   Boolean         @default(false)
  sendEmail                 Boolean         @default(false)
  datePaid                  DateTime?
  credits                   Int             @default(3)
  relatedObject             RelatedObject[]
  externalAuthAssociations  SocialLogin[]
psl=}

Once added, run wasp db migrate-dev so Wasp takes care of all the db migrations, and relaunch your server.

1. In main.wasp add a new dependency @types/passport-google-oauth20. At the time of writing this article, the actual version is 2.0.11 but go ahead and install the latest one.

("@types/passport-google-oauth20", "2.0.11")

The reason why you install @types/passport-google-oauth20 is because Wasp is using passport to handle authentication strategy etc behind the scenes, so that's exactly the types that are used in the backend and that you can expect to be returned.

1. Create a file under src/server/auth/google.ts

2. Add new function getUserFields alongside with type import:

import { Profile } from "passport-google-oauth20";

export async function getUserFields(
  _: unknown,
  args: { profile: Profile }
) {
  const userFields = {
    email: args.profile._json.email,
    profileImage: args.profile._json.picture,
    fullName: args.profile._json.name,
  };
  return userFields;
}

1. Declare your getUserFields function in main.wasp file, by adding getUserFieldsFn property to auth.methods.google object, like so:

  auth: {
    userEntity: User,
    externalAuthEntity: SocialLogin,
    methods: {
      google: {
        getUserFieldsFn: import { getUserFields } from "@server/auth/google.js", // <-- add `getUserFieldsFn` property
        configFn: import { config } from "@server/auth/google.js",
      },
    },
    onAuthFailedRedirectTo: "/",
  },

Function getUserFields is a special function, that Wasp is using to retrieve any user fields that will be added to the database. The second argument of this function is to receive an object, that contains profile of type Profile . This is what is being "passed" to you by Wasp , so that you can "cherry-pick" what you want to be saved into your User record when one will be created.

Whatever object you will return from this function, this is what will be stored in the User table, under the new row. As you can see, I am retrieving profileImage and fullName properties from args.profile._json. object.

You can read more about getUserFields in the linked article, but it's only covering JavaScript file, not TypeScript, so hoping this article helps you to annotate. your codebase better, until Wasp provides you with a type export by itself.

Follow me here on 📖 Hashnode: https://blog.oleggulevskyy.dev/

Follow me on 🐦 Twitter: https://twitter.com/preacher_rourke

I am sharing all the cool stuff I find, daily.

Zed is a new kid on the block in the IDE business but seems to be causing some people to talk about it.

From the first look, it appears to be focusing on blazing speed (just like everything with Rust) and shareability.

While the speed is evident, what does "shareability" mean? The Zed development team frequently promotes this feature - the capability to share projects with your peers by inviting them to a live session. In this session, you can track each other's cursors and engage in pair programming or any other text editing tasks together.

UI

This is one thing I am pretty fond of - their UI is very, very, I mean very minimal. I come to like this kind of thing lately, and for this - UI is very attractive.

And this is their default UI theme. What's not to like? Taking my hat off here. But if you think this is too grim for you, you can treat yourself to any other theme, that comes baked into Zed.

Worth noting, whenever you scroll the Theme from the selection - it immediately applies to the entire editor, giving you a good preview.

Sweet, what's next?

Speed

I mean goddaymn, this seems to be fast. I smell Rust all over it. Even the fact that you can preview the theme on the fly just by going Up and Down on the Theme picker - says a lot about the snappiness of the editor.

However, I also think that the fact that there are no plugins (in my current setup) installed plays a huge factor - nothing blocks the main boot process, no additional operations happen when I open files etc. It's just Rust window and LSP (Language Server Protocol)

User Experience

Well, this one is very very subjective, and I review it from a point of a "lazy and stubborn user" (which I might relate to) so take it with a handful spoon of salt.

First of all, I love their command palette. It's just visually appealing, and snappy (both points above) and seems to be aiming for a variety of options to choose from. Even some Vim commands. However, when I tried to use one of those options, such as vim: quotes, Zed died on me instantly.

I don't even know what this command was supposed to do and was curious to use it. However, after restarting it, it does not crash anymore, nor does it do anything.

Anyway, using something a bit more "traditional" brings the desired result, and does it so fast.

Some things appear to be working out of the box, which is the most important thing IMHO when it comes to IDE, such as LSP.

But I do wonder, if someone will ever be able to focus on TypeScript errors formatting and offer this on a native level, rather than some extension/plugin.

This is not against Zed, but I would be very excited to see this handled one day.

What about Vim?

It claims that it supports Vim and it appears to be in the very early stage, but from what I saw - I was able to use only basic operations/navigations through the document, but having to move from Neovim, I was practically a "turtle" when it comes to navigation. A big chunk of functionality is just not there, or it's not clear how to "enable" it. I.e. navigating from the opening bracket to the closing bracket Shift + 5 or Jumping on empty lines - Cmd + Shift + { / } . So while you can edit words in Vim mode, you can't do much more than that, just yet.

Overall

I am excited about it, mainly because of the simplicity, elegance and speed that it brings to the game, but being an avid Vim user, the IDE is not usable to me at least at this stage. I would be curious to see what others think of it, especially users of VSCode, Fleet, WebStorm etc, but if you are used to some plugins heavy activity, where you have tons of different plugins doing the heavy lifting for you, this might not be your poison. But do give it a try!

To me - managing a terminal can be awkward, especially if you are just dipping your toes into terminal-like life for the first time. Warp makes it easy. (btw, I am not paid or affiliated with Warp in any way - this is my real excitement and experience with it)

Each command is based on blocks, which in itself allows you to do different things with them:

• Copy command

• Copy output

• Find within a block (searching text inside the result of each command, instead of a whole terminal window)

• And some other useful things, that I leave to you to find out... :)

List of my four favorite things so far

Speed

It is fast. Like, native fast. The terminal is done in Rust and you can read more about it here, team behind Warp publishes a fantastic read about the ideology and goals within it. Working with it feels very snappy, with blazingly (yeah, I know you might have saw adjective blazingly everywhere by now) fast response and fast scroll-through. I notice fast scroll-through on purpose, because for me - having M1 Mac and some medium-sized output in the VSCode terminal makes the scrolling experience very painful, with freezes on scrolling. Not a thing anymore with Warp.

Accessibility

One of my favorite things - access Warp at any place, any time. Warp allows you to have a "global" shortcut key, that opens it up regardless of what you are doing. Warp is constantly running my servers now, where I can open output at any given time and check how things are in my garden.

Give it a go, and search for - Global hotkey settings, in the Features tab.

UI

Simple and done with good taste. It comes with prebuilt themes (dark and light) for you to select from, or should you feel expressive enough - you can create your themes. Let me know if that's something that would interest you and I will craft one artisanal, just for you.

Workflows

Create your kind of "templates" or presets, that you can find by description and reuse at any time. More about this some other time, but do let me know if that's something you would be interested in and I will craft another article just for this.

Input experience

The input itself is just a regular text editor. No more "struggles" on how to move cursours from one place to another. If you ever typed text in a simple text area - you will do just fine in Warp.

AI

A thing that buzzes everywhere now, but it AI in Warp has a simple but noble goal to do:

• Remind you of a command you might have forgotten

• Explain a command in case you are not sure what it does

• Suggest you a command for a use case you need

I no longer google stuff like "how to remove a file from git tracking" or "how to replace a text in a string and save it to a file". Everything is available to me in my own editor.

And guess what - I am not paying for it, this is all for free.

However, if you do decide to try and this article was helpful, you can always use my referral link, that supposed to give me more nice themes :)

https://app.warp.dev/referral/2VRWJE

Then, it will be your turn to give away referrals...

Imagine modern monorepos. If you are not using typesafe solutions like tRPC , chances are - you know the pain of synchronizing your types between the backend and front end.

More than that - you are probably also aware that creating new projects, endpoints, databases, scaffolding frontend, and backend is somewhat simplified nowadays compared to what it was 2-3 years ago, but still - one of the most tedious tasks there is. I for one am not interested in repeating the same thing I do for different projects. I want to write logic, I want to create products.

So, you can either turn to some pre-built by someone boilerplate, that either is open source and more often than not crappy and outdated, or a paid one, that is actively maintained but pricey. And even after that, it will be like learning a completely new codebase, to get the grip of the boilerplate ropes.

So what then, CLI, to scaffold our boilerplate? Something like T3? You could, but it's serverless stuff, that you might not necessarily need/want. What if you need a fully functioning backend + frontend?

Hold the door: here comes in Wasp - it's neither of those options listed above, but provides you with way more than just a boilerplate.

Wasp - is a configuration language, it's not a programming language. If you learned how to read the all-mighty JSON, you will be most likely able to grasp Wasp. I did - it means anyone can.

Ultimately, you create a file .wasp and tell Wasp compiler:

1. what kind of endpoints you need, what they do (read or write);

2. what your database should look like

3. what your frontend routes should look like

4. what authentication methods do you want to use

...and hit the command in your terminal to generate a project, that does exactly that:

• have all the stuff you need to be generated for you in a clear, unobfuscated way (you can navigate yourself in the generate output folder even)

• creates a database for you

• handles migrations

• makes sure your frontend knows your backend types (full-stack type safety)

• and many more things, that I have yet to discover myself!

Pretty neat project structure, from the get-go

Now that I am done selling it, let me tell you my initial thoughts about it and the project overall.

Initial feeling

I love engineering, new ideas, new projects and things related to DX. I find it pretty important to have good DX for the quality of the product's life (whatever product this is). If you have an excellent product but shitty, legacy code, that does not scale or is just a nightmare to maintain you are almost guaranteed to have trouble finding the right people to work on it (you will find people, but they will leave one way or another). Welp, that's just my belief, does not necessarily make it right.

This brings me to the point, that what Wasp seems to be aiming for is to gap the bridge backend and front, where anyone even with a minimum of experience in both fields can create full-stack apps. It spins up a nodejs server for you and handles DB connection, migrations, and data modeling (to a certain level of course). So, the goal is noble but I only have one fear - abstraction. Nowadays all our technology is abstracting so much from the basics (which is expected), that new people coming into the field can achieve the same projects/goals but have no idea how things work under the hood.

Abstraction simplifies development, but it also puts you in a very tricky position if things go wrong. And, you are no longer in control of your codebase/project. You depend on yet another tool, for this tool to do well and do the job correctly. If tomorrow there is a bug that nobody caught in this tool - your end users will be affected.

Getting started

Abstraction is one thing, but I like shiny new tools and this seems intriguing, so I jump over to the documentation "Get started" section.

All is clear until the Listing tasks, as it doesn't matter which language you are choosing for your app (JS vs TS)

As my choice is TS, when working on Listing tasks, the article only focuses on JS (which it says in its title, so no blame). But, I think that TS is a very important piece of info to include, so I was expecting the very same implementation shown in the same article, but in TS also. Instead, I had to find a "TypeScript support" separated where it is written how to implement this using TS. The example given in the TS article also derails from the JS article (focuses on plural tasks vs singular) so it's a bit confusing and hard to grasp at first.

Because really, the only difference between JS and TS implementations is one extra import statement:

import { GetTasks } from "@wasp/queries/types"

...and annotate the function with the type like so:

export const getTasks: GetTasks = async (args, context) => { 
    return context.entities.Task.find any();
};

Hence, I think it deserves a life in the same article :)

Hard to debug

When transitioned into listing tasks in React component, I encountered an error where TS could not find my getTasks declaration.

Not only do I have no idea why this default export seems to be missing, but I can't also find the package /queries/* to try to debug it (see if the file has been generated or not), and that's because my IDE is not able to Go To Definition, while I can't find @wasp package manually (in the .wasp folder, in the src folder).

In the end, I managed to find the folder where queries are being imported from, but no file in question, so had to turn to the community for help.

With help of the community (a dev and devrel, I believe) we managed to pin down what was happening and fix the issue. So just to be clear, my issue here is not with the bug itself, as this is just an implementation detail and I was trying to do weird things (like install react 18) but with the abstraction itself, which complicates the experience in case things go south.

And I am not sure if it's my LSP that messes up with me or something else entirely, but my LSP rarely messes with me, so I gave it a credit of trust and blamed abstraction.

Community

The guys are great, helpful, replying to questions openly and pretty fast. One of the guys ( @Vinny ) offered to jump on the call with me and the issue I had was resolved very fast, so that's dope! I can't stress enough how important it is to have good/proper relationships with your end user (via any way possible - support, account manager etc).

In this case, even if I am skeptical about the entire thing and I have hiccups on the way to what the project offers, I know that a bunch of people have got my back and are ready to jump on the call with me to resolve this straight away. Whereas, if I try another project/product, that offers the same or alternative idea, the chances are - I will just abandon the thing from the get-go and get back to the traditional way of building things.

Overall

• By the time I reach the chapter on Updating the list, I find myself enjoying the simple experience there is. Especially I liked the fact that the query from the client side is automatically invalidated by the Wasp, therefore the data on the creation of new tasks updated itself automatically. This was unexpected but I didn't know I wanted this until I saw it 🙂 There seems to be a conversation about this topic, where the dev team wants to allow overriding this behavior which I can see the importance of, but - it just worked.

• It is dammmn fast. Like, the start and stop of the server are snappy, and the commands are fast. The client-side changes do take some time to refresh, and I wonder if this scales with the app, but the initial "behind the scenes" stuff seems to be fast. And again, the experience of creating different "endpoints" and functionality helps us move faster. Some cool tRPC stuff right there.

• Excited to try this out in a real project rather than a to-do list... just need to carve out some time for it to start. :D

Next

I have an idea that I would love to try Wasp out for, as it seems like a good fit for it. Initially, I wanted to use NextJS with tRPC for it, but it didn't go as planned (mainly because of Nextjs) due to how Google Auth works inside iframed applications (it just doesn't). So, I hope that more of a client-side authentication will be possible (like it's very easy with Firebase). This is where I will have a chance to try more authentication in Wasp, sending emails and deploying. 🤞

A company where I work started the migration process from Zendesk Help Center (it's where all our documentation is hosted) to React based Docusaurus. Big challenge that they faced is to migrate all of HTML-based articles to Markdown. In addition to that - each Markdown file has to be of .mdx file format (which would allow. them to import assets, components and all that kind of good stuff that you usually use nowadays).

Sounds like a good place for a CLI tool, right? - that's what I thought.

Preparation

There is not much to it really, so I will be quick.

1. Get all the data needed somewhere - which is in my case, a list of all articles that our documentation team wanted to migrate.

For that, I decided to export all the articles data from Zendesk Help Center into Google Spreadsheet. If you ever find yourself in the same position - use Awesome Table Connector addon, it's a seriously helpful tool.

1. Decide on which programming language to choose from. There are only 2 languages in my belt (for now) I can choose from - JS or Go. But, I do prefer Go, so the choice here was obvious. And, as I soon will find out this was the right choice.

CLI Tool

Now that I have my data and chose the language, my CLI tool was fairly simple:

• With help of Google Service accounts, fetch list of HTML bodies from prepared Google Spreadsheet
• Transform each HTML body into a Markdown file, where the html-to-markdown package does all the heavy lifting.
• In the process of transforming, collect all the images and their URLs from <img src=".." /> tags and download them. Had to be extra careful here though, as I am big fan of Go and its goroutines feature, making a big amount of network requests to download them (1200 image URLs) would lead to some troubles such as timeouts etc, thus it had to be batched.
• Add imports of those images to each transformed .mdx file.

First version result

Because the tool is not for me personally, but for other teams, and the migration is an ongoing process for them, the tool cannot have hard coded values in it (such as Spreadsheet ID, for example) in order to not lose flexibility and be useful in the long run.

This resulted in a small handy CLI tool that did the job, that requested you to provide a Spreadsheet ID, Range where to look for and making sure you added the service account to the file's sharing list.

Replace CLI with Wails

Now, that's all nice and cool, but I remembered, absolutely randomly, that I stumbled upon a Go library called Wails.

This tool is designed to give Go developers means to build native desktop apps with front-end technologies, using HTML / CSS / JS. It's aiming to be an alternative to Electron (uses NodeJS as its backend) and another famous alternative out there - Tauri (which uses Rust as its backend). I am a web developer, so this sounds like an easy way to create a great UI.

It is truly amazing what the team behind Wails put together - intuitive API, lightweight build output (15 Mb for an application that used React + Tailwind + bundled all together to be native application). One big difference between Electron and Wails - they don't ship "browser" inside the bundle to the end-user. Another awesome thing, that I personally love - is binding generation between your Go codebase and JS. I love type safety, and this allows me to go fast and safe, making correct calls from front-end calls to Go and having a TypeScript compiler telling me what arguments are expected and will be returned.

So, in order to transform my CLI into a desktop app, I went for React + Tailwind + Vite. It took me half of the day in order to move the logic from CLI to the newly desktop app powered by Wails. And this is the result!

I think that's a pretty decent looking desktop application, compared to a boring CLI.

If you are interested - I'd be happy to write down the actual implementation guide in Wails, showing how you can achieve the same. Let me know :)