DEV Community: digitallyinduced

thin.dev: Realtime-by-default BaaS (Backend-as-a-Service)

digitallyinduced — Mon, 02 May 2022 16:56:07 +0000

In this article, you will learn how to use Thin Backend's react API to build a chat application like WhatsApp or Signal, deploying it to production along the way - all within 10 minutes!

Thin is a new Backend-as-a-Service offering by digitally induced! React (or Svelte,...) apps built using its toolkit are realtime by default, meaning it's easier to build an app that reacts to data updates everywhere all the time than it is to keep data out-of-date!

Preparation

I assume a basic understanding of relational databases and React (including hooks) throughout this article. I also assume you have a GitHub account and know how to commit and push using git. You should also have a recent version of node and npm installed.

Minute 1: Sign up for Thin Backend

Go to https://thin.dev/NewSession, choosing "Continue with GitHub". After going through all the required steps, you will be greeted by your project overview:

Minute 2: Create the project

Click on the + New Project button and enter a name for your project (for example, "Realtime Chat"), and click on Create Project when you're happy with it.

You'll be greeted by the Onboarding:

Feel free to use the Onboarding later to build a to-do app, but we will continue differently.

Click on Frontend in the left navigation bar. We'll use this tab to generate a boilerplate frontend.

Click on + New Vercel Project. Vercel is a platform to deploy frontend frameworks and static sites. We'll use it to get our frontend deployed quickly and easily.

The following screen will greet you:

Choose the TypeScript React Starter template from among the choices, but feel free to take a quick look at the other options. Don't be surprised that a new tab will open for Vercel.

Choose GitHub as a provider, also on the following screen. Enter your project's name (it doesn't have to match exactly) as a repository name:

Finally, click on Create to actually create your project. It'll take a short while, after which you will be prompted to configure your project:

By clicking on the Learn More link, a new tab will open, showing you the value to enter into the input box. This will be the URL at which the backend of the chat app is accessible. Simply click on the displayed link to copy it and enter it on Vercel.

Then click the Deploy button. It will take a few seconds, after which your project is already online, and you will be redirected back to Thin!

Let's check that everything is working so far by clicking the Frontend button in the left sidebar. It should redirect you to the login for your new chat app. Create a new account here, then continue below.

Minute 3-4: Modifying the schema

We could already create users because every new Thin Backend project automatically comes with authentication built-in. You can see some of that implementation by checking out the users table in the schema designer. To do that, click on Schema in the left navigation bar on Thin Backend. You should see a screen like this:

As you can see, a users table is already set up. Users, by default, have a few columns that are relevant for Thin Backend that we don't need to care about. For us, only the email is interesting since we can use it to show to users later to choose with whom to chat.

At the bottom, you can also see a section titled Policies. Thin Backend uses PostgreSQL under the hood. Policies are a way to allow users to access and modify the rows of tables only if some conditions are met. By default you can see that users can read if: id = ihp_user_id() and write if: false. That means users can only see their own user record, and no user can edit any record.

For simplicity, we'll allow all users to view the records of all users to have an easier time listing all the options to who we can send messages. To do so, right-click on the policy and select Edit Policy. A modal will open, allowing you to edit the policy. Change the content of the Visible if box to true.

This is a terrible idea for an actual production app. We're simply doing this for simplicity and to get something running asap.

A little popover will appear after you save:

When making changes to the schema, those changes do not immediately apply to the underlying database. Instead, Thin Backend uses Migrations to allow you to customize how the data in the schema should be converted.

For now, we'll just ignore the popover and make a few more changes to the schema.

If we want to allow users to chat with one another, we need to save the messages they send. To do that, we'll create a new table. Click on the little + next to the Tables header on the left, and a modal will open, prompting you for a name. Let's call this table messages:

Click on Create Table.

You can notice a few things now. First, there's a little icon next to the messages table in the list on the left:

This icon tells us that we haven't created any policies for this table yet, which will make it inaccessible to our frontend for security reasons. We'll fix that in a bit.

You should also notice three large buttons in the list of columns. Right now, our messages only have an id, but they should get some more columns to save who sent them, who they were sent to, when they were sent, and what content they contain. Thin Backend suggests a few columns that are commonly used. Two of those we want: created_at and user_id. We'll use created_at to sort the messages later, and user_id is a good choice for saving who sent the message.

If you click on those two suggestions, you will notice a few things happen.

First, the columns are added to the table as expected. Additionally, at the bottom, you will see a policy has been created. That's because Thin Backend assumes that once you link something to a user, only that user should have access to it. That's a very reasonable default and dangerous to forget! We will only have to make a slight adjustment in our case in a bit.

Second, below the policies, you can see a few indices created. Thin Backend assumes that queries based on the user_id and created_at columns are common, so it creates indices for those too. I suggest keeping them for our project, but if Thin Backend generates something you don't need for your project, you can delete it without issue.

The goal is to generate the correct thing for 90% of cases and allow you to adjust everything for the other 10% of cases.

We still require one more column: a recipient_id, so we know to whom a message was sent!

Click on the little + icon in the top-right to create that column. A modal will open, allowing you to configure a new column for the table.

Let's set the name to recipient_id. You'll notice Thin Backend notices that a UUID is expected here and selects the correct type for the column for us. We'll only have to change the default value. There's no sensible default since we always want to set the recipient_id ourselves. Simply change the dropdown’s value from uuid_generate_v4() to no default.

You can now click on Create Column.

We now have to add a foreign key constraint to that column, as Thin Backend did not recognize that recipient_id should reference the users table. To do so, right-click the newly created column and click on Add Foreign Key Constraint. A modal should open:

The defaults are precisely like we want, so we can click on Add Constraint. You can see that it worked because it says' FOREIGN KEY: users' on the right side of the column's details.

Now that we know when messages are created and who sent them to whom, we can add the last required column, which will contain the message's contents: content.

Click on the little + in the top-right again, calling the new column content, keeping the default type of Text and no default. After clicking on Create Column, your messages table should look like this:

There's only one more step missing before migrating the database to our new schema. We have to edit the messages policy. Right now, users are only able to read messages they sent themselves, but they also should be able to read messages they receive. Therefore, right-click the Users can manage their messages policy at the bottom, choosing Edit Policy in the context menu.

Change the Visible if part of the policy from user_id = ihp_user_id() to user_id = ihp_user_id() OR recipient_id = ihp_user_id(), which will allow users to read all rows where either the user_id or the recipient_id is equal to their user record’s id.

After clicking on Update Policy, your table should look like this:

We can finally apply these changes to the database by clicking on the Migrate DB button at the bottom of the screen. Thin Backend will automatically generate a new migration. Migrations are nothing more than the SQL statements required to get the current database schema to match the schema with our edits. If we had production data already, we might have to be careful in converting from one state of the database to the next to correctly convert the data, which would mean manually adjusting the generated migration. Since we don't have any important data yet, though (only the user we created when signing up to our app), we can safely save and run the generated migration by clicking on the Run Migration button:

After clicking the button, the migration will run, which should take at most a few seconds, after which you will see a list of past migrations, currently only containing the one we just created. A little green arrow at the right indicates that Thin Backend executed the migration successfully:

By clicking on Schema Designer in the top navigation, you can see that the Unmigrated Changes message is now gone, indicating that the database matches what we see in the Schema Designer.

Minute 4: Cloning the Frontend locally

Now that we've finished our backend, we can take care of our frontend. The first step will be to clone our generated frontend repository so that we can work with it locally:

git clone https://github.com/YOURUSERNAME/REPOSITORYNAME.git
cd REPOSITORYNAME

When you open the project with your favorite code editor, for example, VSCode, you will see the following folder structure:

We will primarily be working within the app.tsx file, containing all the react code. If you were to create a production-ready app, you would, of course, set up the project to your liking, but for simplicity's sake, we will stay in a single file for this article.

Before we go and write code, we'll want to get a development server running and connected to our backend to verify that everything works as expected before deploying it.

We must first tell the frontend where it can access our backend by setting the BACKEND_URL environment variable. The easiest way to do that is to create a file called .env in the project directory and add a line like this:

BACKEND_URL=https://REPLACE_ME

You can get the value for the right of the equals sign from Thin Backend itself - it's the same value we entered when we created the project on Vercel. You can find it by clicking on Docs in the left navigation. You will see a section in the right sidebar, as in the screenshot below. Simply click on the URL to copy it.

So in my case, the final .env file would look like this:

Next, let's test that everything's working as expected by first installing all dependencies and then starting the development server:

npm install
npm run dev

If you now open localhost:3000, you will be redirected to a login form, where you can log in using the details you used when creating an account on your own site earlier - or you can create a new user, of course.

Once logged in, you should see a mostly empty screen, apart from a slightly darkened bar at the top with your email. If you click on your email, you get the option to log out again.

The last thing we'll do before we implement our frontend is to install the project-specific types, so we can use our editor's autocompletion and don't get any type errors in our editor.

Open the Schema Designer on Thin Backend, and click on Type Definitions in the top navigation. By clicking on the npm install ... command for TypeScript, and running that locally in our project's directory, we should be all set!

clone
add BACKEND_URL env variable
install types

Minute 5: Listing users to chat with

A chat app without the option for users to chat with others is pretty useless. To chat with someone else, we first need to choose with whom to chat. For simplicity, we'll simply list all users that signed up for our app - so everyone can send messages to everyone else.

Open the app.tsx file. There's a bit of code in there already, giving us a basic structure. Feel free to take a look to understand what's going on. Most imports are added only for convenience; they aren't actually used yet.

For listing the users, let’s create a component called Users to list all users we can chat with. To do so, create a new function in app.tsx called Users. I’ll add the function after the AppNavbar component. For now, I’ll simply return an empty div from it:

function Users() {
    return <div>
    </div>
}

Let's render that component by adding it below the <AppNavbar/> line in the App component (between lines 15 and 16). The App component should now look like this:

function App() {
    // With `useQuery()` you can access your database:
    // 
    //     const todos = useQuery(query('todos').orderBy('createdAt'));

    return <ThinBackend requireLogin>
        <div className="container">
            <AppNavbar/>
            <Users/>
        </div>
    </ThinBackend>
}

Let's get all users from the backend by modifying the Users component. Inside it, add a new variable called users, setting its value to the result of the useQuery hook from Thin Backend:

const users = useQuery();

The useQuery hook allows us to fetch information from the backend, which will automatically refresh in realtime whenever the data on the backend changes. Your editor might give you a type error right now, as useQuery expects a query as an argument, so it knows what to fetch. Let's pass it a simple query to fetch all users:

const users = useQuery(query('users'));

You might have noticed that you got autocompletion for every part of this, which is one benefit of using typescript and installing the types provided by Thin Backend.

The users variable now contains the list of all users or null if the fetch isn't completed. Let's deal with that second case first, by adding a simple if statement to return a "Loading..." message to display:

if (users === null) {
    return <div>Loading...</div>
}

Otherwise, we’ll render the users as a list like this:

return <div>
    {users.map(user => <div key={user.id}>
        <button className="btn btn-link">
            {user.email}
        </button>
    </div>)}
</div>

Currently, the Users component looks like this:

function Users() {
    const users = useQuery(query('users'));
    if (users === null) {
        return <div>Loading...</div>
    }
    return <div>
        {users.map(user => <div key={user.id}>
            <button className="btn btn-link">
                {user.email}
            </button>
        </div>)}
    </div>
}

If you open the local app in your browser, you might see a short "Loading..." message appear, quickly replaced by an entry for every user you created so far - which is probably just yourself.

Before we continue, let's create a few users to chat with, so it's not quite as evident that we're only talking to ourselves. Log out and create 2-3 new user accounts, so the list is a bit more populated:

You might be redirected to the deployed version of your app after creating accounts. If that happens, simply go back to [localhost:3000](http://localhost:3000) to create the next account or log in there.

With a few more users available to chat, we can now hide ourselves from the list by adding a simple filter to the query.

Let’s change the line that defines the users variable to the following:

const users = useQuery(query('users').whereNot('id', getCurrentUserId()));

If you check the list now, the user you logged in as should not appear in the list anymore.

We modified the query('users') part using .whereNot('id', getCurrentUserId()). getCurrentUserId is a function imported from thin-backend which will return the current user id as long as you are logged in. whereNot allows you to filter the data in the database by only including rows where the column passed as a first argument ("id") does not equal the second argument. So effectively, we query for all users where the "id" does not match the currently logged-in user's id, resulting in all users except the one we logged in as.

Now that we have a list of users to chat with, let's quickly allow selecting them. We'll add a simple state variable to the App component to keep track of the user we've currently selected:

// add this import so we can make TypeScript happy
import type { User } from 'thin-backend';

// add this to the App component
const [selectedChat, setSelectedChat] = useState<User | null>(null);

Let’s add a onUserSelect prop to the Users component which is called by an onClick handler on the button tag:

function Users({ onUserSelect }: { onUserSelect: (user: User) => any }) {
    ...
            <button
                className="btn btn-link"
                onClick={() => onUserSelect(user)}
            >
    ...

Now we can pass the setSelectedProp function to the Users component with that prop:

// replace this line in the App component
<Users/>
// with this one
<Users onUserSelect={setSelectedChat}/>

Now the App component keeps track of the user we're chatting with!

Minute 6: Allow sending messages to users

Next, let's create the Chat component, which we'll eventually use to chat with another user; for now, we'll just use it to display the currently selected user.

Create a Chat function component that accepts a user prop of type User and renders a simple div containing the user’s email:

function Chat({ user }: { user: User }) {
    return <div>
        {user.email}
    </div>
}

Let’s render that component from our App component by adding it below the Users component if the selectedChat isn’t null, and pass the selectedChat to it:

function App() {
    const [selectedChat, setSelectedChat] = useState<User | null>(null);

    return <ThinBackend requireLogin>
        <div className="container">
            <AppNavbar/>
            <Users onUserSelect={setSelectedChat}/>
            {selectedChat === null ? null : <Chat user={selectedChat}/>}
        </div>
    </ThinBackend>
}

When clicking on the different users, the email below the list should now change in the browser.

Let’s change the markup a bit to render the Chat component on the right side next to the Users:

function App() {
    const [selectedChat, setSelectedChat] = useState<User | null>(null);

    return <ThinBackend requireLogin>
        <div className="container">
            <AppNavbar/>
            <div className='row'>
                <div className='col'>
                    <Users onUserSelect={setSelectedChat}/>
                </div>
                <div className='col'>
                    {selectedChat === null ? null : <Chat user={selectedChat}/>}
                </div>
            </div>
        </div>
    </ThinBackend>
}

Things should now look something like this:

Now that we have a Chat component with access to the user we've selected, we can finally create the necessary code to send messages to that user.

Let’s add a form element inside the Chat component with a simple input and a submit button, which we can use to send messages:

function Chat({ user }: { user: User }) {
    return <div>
        {user.email}
        <form className="input-group mt-4">
            <input
                type="text"
                className="form-control"
                placeholder="Type a message..."
                aria-describedby="send-button"
                autoFocus
            />
            <button type='submit' className="btn btn-primary">Send</button>
        </form>
    </div>
}

I have added a bit of simple markup to make it look prettier.

To make this work, we'll need to handle the submit event of the form - we can do that by creating a handleSend function within the Chat component that we pass to the onSubmit attribute of the form element:

// add this before the return in Chat:
function handleSend(event: FormEvent<HTMLFormElement>) {
      event.preventDefault();
      const input = event.currentTarget.elements.namedItem('message') as HTMLInputElement;
      // this is where the magic happens:
      createRecord('messages', {
          recipientId: user.id,
          content: input.value,
      });
      input.value = '';
  }

The important call here is the one to createRecord. Thin Backend provides this function. The first argument tells Thin Backend to create a new record in the messages table, and the second argument contains all the required fields we need to set for the record to be complete (it'll use the default values if we don't override them). Since Thin Backend uses the currently logged-in user's id as user_id by default (as defined in the schema) and generates a new id for the message automatically, we only need to set the recipient_id to the id of the user we've selected to chat with, and the content to the input's value.

Minute 7: Display sent messages

There's only one problem: once we send the message, there's no way to read it!

So the next step is to display all messages sent into the current chat.

To do so, we'll write another query using useQuery inside the Chat component. Let's start simple and get all messages the user has access to:

const messages = useQuery(query('messages'));

We can display this list of messages by adding these lines above the form tag and below the {user.email} line:

{messages?.map(message =>
    <div
        key={message.id}
        className={'message ' + (message.userId === getCurrentUserId() ? 'from-me' : 'to-me')}
    >
        <div className='message-content'>
            {message.content}
        </div>
    </div>
)}

All we're doing here is mapping over the messages, displaying each message's content inside two divs. We also assign CSS classes based on whether the current user sent the message or received it by comparing the message's userId to the current user's id (accessed with getCurrentUserId()).

For the CSS classes to do anything, add the following styles to public/app.css:

.message.from-me {
    text-align: right;
    padding-left: 2rem;
}

.message.to-me {
    padding-right: 2rem;
}

.message .message-content {
    border-radius: 5px;
    margin-top: 1rem;
    padding: 0.5rem;
    display: inline-block;
    text-align: left;
}

.message.to-me .message-content {
    background-color: lightgray;
}

.message.from-me .message-content {
    background-color: lightblue;
    right: 0;
}

I won't go over this in detail; it just makes things look a bit better. Feel free to take a closer look if you want, though.

After changing the CSS, you might have to reload the app in the browser to see the effects.

Currently, we display all messages in every chat and no particular order. Since that doesn't make sense, let's modify the query we use to fetch the messages only to fetch those messages sent to us from the user we have selected to chat with and those we sent to them. After query('messages'), we can add a .where(..) condition as we did earlier, filtering the messages we sent:

const messages = useQuery(
        query('messages')
                .where('userId', getCurrentUserId())
);

That still doesn’t limit the messages to those sent to the selected person though, so we’ll add another .where condition based on the recipient:

const messages = useQuery(
    query('messages')
        .where('userId', getCurrentUserId())
        .where('recipientId', user.id)
);

Multiple where conditions like this will be combined using AND.

Now we have all of the messages we sent, but we’re now missing the messages we received. To fix that, we can add a set of conditions using .or:

const messages = useQuery(
    query('messages')
        .where('userId', getCurrentUserId())
        .where('recipientId', user.id)
        .or(
            where('userId', user.id)
            .where('recipientId', getCurrentUserId())
        )
);

.or takes a list of conditions just as you can add them to query('messages'). You might have to add an import for where to the import list of thin-backend at the top of the file.

.or uses all previous conditions for the left side of the resulting OR condition. If you want a bit more clarity, you can wrap the initial conditions with a single call to .where:

const messages = useQuery(
    query('messages')
        .where(
            where('userId', getCurrentUserId())
            .where('recipientId', user.id)
        )
        .or(
            where('userId', user.id)
            .where('recipientId', getCurrentUserId())
        )
);

I, personally, don't think that's necessary, though.

If we check the result in the browser, messages will now only show in the correct chat! However, even if the order of messages might look correct, we have done nothing to ensure this will stay consistent. To always ensure that messages are displayed in the correct order, we can add a simple .orderBy('createdAt') to the query:

const messages = useQuery(
    query('messages')
        .where(
            where('userId', getCurrentUserId())
            .where('recipientId', user.id)
        )
        .or(
            where('userId', user.id)
            .where('recipientId', getCurrentUserId())
        )
        .orderBy('createdAt')
);

And finally, the correct messages show, in the proper order!

Minute 8: Realtime

We haven't done anything to make our app realtime yet... But the useQuery hook is realtime by default, meaning we don't have to do anything! Thin Backend will push new data to each client who requires it over a WebSocket connection. You can quickly try it out by opening a new private window in which you sign in as another user, sending messages between clients - the messages will show up in each browser without requiring a reload of the page!

I guess we can use this time for doing something else then.

Minute 8b: Commit and push (deploy)

Now that we've finished the frontend let's deploy it to production. Commit all changes and push them to your repository:

git add app.tsx public/app.css package.json package-lock.json
git commit -m "implement realtime chat"
git push

Vercel will notice a change on the main branch of our repository and deploy the changes automatically.

Enjoy your new app and possibly spare time!

Moving on

From here, you can continue playing around with Thin Backend. Maybe you want to allow users to set a different display name instead of displaying their email? Maybe you want users to request a chat with others, so they can't just send messages to anyone willy-nilly? Perhaps you want to implement group chat functionality?

If you don't feel comfortable trying things out alone, you might also want to follow the normal Onboarding process. It'll lead you through creating another app, similar to this article, but possibly give you some new information not covered here or covered differently.

What will you build with Thin Backend? Tell us in the comments!

Build and deploy a real-time react chat app in under 10 minutes

digitallyinduced — Fri, 25 Feb 2022 10:11:07 +0000

In this article, you will learn how to use IHP Backend's react API to build a chat application like WhatsApp or Signal, deploying it to production along the way - all within 10 minutes!

IHP Backend is a new Backend-as-a-Service offering by digitally induced! React apps built using its toolkit are realtime by default, meaning it's easier to build an app that reacts to data updates everywhere all the time than it is to keep data out-of-date!

Preparation

Minute 1: Sign up for IHP Backend

Go to https://ihpbackend.digitallyinduced.com/NewSession, choosing "Continue with GitHub". After going through all the required steps, you will be greeted by your project overview:

Minute 2: Create the project

Click on the + New Project button and enter a name for your project (for example, "Realtime Chat"), and click on Create Project when you're happy with it.

You'll be greeted by the Onboarding:

Feel free to use the Onboarding later to build a to-do app, but we will continue differently.

Click on Frontend in the left navigation bar. We'll use this tab to generate a boilerplate frontend.

Click on + New Vercel Project. Vercel is a platform to deploy frontend frameworks and static sites. We'll use it to get our frontend deployed quickly and easily.

The following screen will greet you:

Choose the TypeScript React Starter template from among the choices, but feel free to take a quick look at the other options. Don't be surprised that a new tab will open for Vercel.

Choose GitHub as a provider, also on the following screen. Enter your project's name (it doesn't have to match exactly) as a repository name:

Finally, click on Create to actually create your project. It'll take a short while, after which you will be prompted to configure your project:

Then click the Deploy button. It will take a few seconds, after which your project is already online, and you will be redirected back to IHP Backend!

Minute 3-4: Modifying the schema

We could already create users because every new IHP Backend project automatically comes with authentication built-in. You can see some of that implementation by checking out the users table in the schema designer. To do that, click on Schema in the left navigation bar on IHP Backend. You should see a screen like this:

As you can see, a users table is already set up. Users, by default, have a few columns that are relevant for IHP Backend that we don't need to care about. For us, only the email is interesting since we can use it to show to users later to choose with whom to chat.

At the bottom, you can also see a section titled Policies. IHP Backend uses PostgreSQL under the hood. Policies are a way to allow users to access and modify the rows of tables only if some conditions are met. By default you can see that users can read if: id = ihp_user_id() and write if: false. That means users can only see their own user record, and no user can edit any record.

This is a terrible idea for an actual production app. We're simply doing this for simplicity and to get something running asap.

A little popover will appear after you save:

When making changes to the schema, those changes do not immediately apply to the underlying database. Instead, IHP Backend uses Migrations to allow you to customize how the data in the schema should be converted.

For now, we'll just ignore the popover and make a few more changes to the schema.

Click on Create Table.

You can notice a few things now. First, there's a little icon next to the messages table in the list on the left:

This icon tells us that we haven't created any policies for this table yet, which will make it inaccessible to our frontend for security reasons. We'll fix that in a bit.

You should also notice three large buttons in the list of columns. Right now, our messages only have an id, but they should get some more columns to save who sent them, who they were sent to, when they were sent, and what content they contain. IHP Backend suggests a few columns that are commonly used. Two of those we want: created_at and user_id. We'll use created_at to sort the messages later, and user_id is a good choice for saving who sent the message.

If you click on those two suggestions, you will notice a few things happen.

First, the columns are added to the table as expected. Additionally, at the bottom, you will see a policy has been created. That's because IHP Backend assumes that once you link something to a user, only that user should have access to it. That's a very reasonable default and dangerous to forget! We will only have to make a slight adjustment in our case in a bit.

Second, below the policies, you can see a few indices created. IHP Backend assumes that queries based on the user_id and created_at columns are common, so it creates indices for those too. I suggest keeping them for our project, but if IHP Backend generates something you don't need for your project, you can delete it without issue.

The goal is to generate the correct thing for 90% of cases and allow you to adjust everything for the other 10% of cases.

We still require one more column: a recipient_id, so we know to whom a message was sent!

Click on the little + icon in the top-right to create that column. A modal will open, allowing you to configure a new column for the table.

Let's set the name to recipient_id. You'll notice IHP Backend notices that a UUID is expected here and selects the correct type for the column for us. We'll only have to change the default value. There's no sensible default since we always want to set the recipient_id ourselves. Simply change the dropdown’s value from uuid_generate_v4() to no default.

You can now click on Create Column.

We now have to add a foreign key constraint to that column, as IHP Backend did not recognize that recipient_id should reference the users table. To do so, right-click the newly created column and click on Add Foreign Key Constraint. A modal should open:

The defaults are precisely like we want, so we can click on Add Constraint. You can see that it worked because it says' FOREIGN KEY: users' on the right side of the column's details.

Now that we know when messages are created and who sent them to whom, we can add the last required column, which will contain the message's contents: content.

After clicking on Update Policy, your table should look like this:

We can finally apply these changes to the database by clicking on the Migrate DB button at the bottom of the screen. IHP Backend will automatically generate a new migration. Migrations are nothing more than the SQL statements required to get the current database schema to match the schema with our edits. If we had production data already, we might have to be careful in converting from one state of the database to the next to correctly convert the data, which would mean manually adjusting the generated migration. Since we don't have any important data yet, though (only the user we created when signing up to our app), we can safely save and run the generated migration by clicking on the Run Migration button:

By clicking on Schema Designer in the top navigation, you can see that the Unmigrated Changes message is now gone, indicating that the database matches what we see in the Schema Designer.

Minute 4: Cloning the Frontend locally

Now that we've finished our backend, we can take care of our frontend. The first step will be to clone our generated frontend repository so that we can work with it locally:

git clone https://github.com/YOURUSERNAME/REPOSITORYNAME.git
cd REPOSITORYNAME

When you open the project with your favorite code editor, for example, VSCode, you will see the following folder structure:

Before we go and write code, we'll want to get a development server running and connected to our backend to verify that everything works as expected before deploying it.

BACKEND_URL=https://REPLACE_ME

You can get the value for the right of the equals sign from IHP Backend itself - it's the same value we entered when we created the project on Vercel. You can find it by clicking on Docs in the left navigation. You will see a section in the right sidebar, as in the screenshot below. Simply click on the URL to copy it.

So in my case, the final .env file would look like this:

Next, let's test that everything's working as expected by first installing all dependencies and then starting the development server:

npm install
npm run dev

Once logged in, you should see a mostly empty screen, apart from a slightly darkened bar at the top with your email. If you click on your email, you get the option to log out again.

The last thing we'll do before we implement our frontend is to install the project-specific types, so we can use our editor's autocompletion and don't get any type errors in our editor.

Open the Schema Designer on IHP Backend, and click on Type Definitions in the top navigation. By clicking on the npm install ... command for TypeScript, and running that locally in our project's directory, we should be all set!

clone
add BACKEND_URL env variable
install types

Minute 5: Listing users to chat with

function Users() {
    return <div>
    </div>
}

Let's render that component by adding it below the <AppNavbar/> line in the App component (between lines 15 and 16). The App component should now look like this:

function App() {
    // With `useQuery()` you can access your database:
    // 
    //     const todos = useQuery(query('todos').orderBy('createdAt'));

    return <IHPBackend requireLogin>
        <div className="container">
            <AppNavbar/>
            <Users/>
        </div>
    </IHPBackend>
}

Let's get all users from the backend by modifying the Users component. Inside it, add a new variable called users, setting its value to the result of the useQuery hook from IHP Backend:

const users = useQuery();

const users = useQuery(query('users'));

You might have noticed that you got autocompletion for every part of this, which is one benefit of using typescript and installing the types provided by IHP Backend.

if (users === null) {
    return <div>Loading...</div>
}

Otherwise, we’ll render the users as a list like this:

return <div>
    {users.map(user => <div key={user.id}>
        <button className="btn btn-link">
            {user.email}
        </button>
    </div>)}
</div>

Currently, the Users component looks like this:

function Users() {
    const users = useQuery(query('users'));
    if (users === null) {
        return <div>Loading...</div>
    }
    return <div>
        {users.map(user => <div key={user.id}>
            <button className="btn btn-link">
                {user.email}
            </button>
        </div>)}
    </div>
}

If you open the local app in your browser, you might see a short "Loading..." message appear, quickly replaced by an entry for every user you created so far - which is probably just yourself.

You might be redirected to the deployed version of your app after creating accounts. If that happens, simply go back to [localhost:3000](http://localhost:3000) to create the next account or log in there.

With a few more users available to chat, we can now hide ourselves from the list by adding a simple filter to the query.

Let’s change the line that defines the users variable to the following:

const users = useQuery(query('users').whereNot('id', getCurrentUserId()));

If you check the list now, the user you logged in as should not appear in the list anymore.

We modified the query('users') part using .whereNot('id', getCurrentUserId()). getCurrentUserId is a function imported from ihp-backend which will return the current user id as long as you are logged in. whereNot allows you to filter the data in the database by only including rows where the column passed as a first argument ("id") does not equal the second argument. So effectively, we query for all users where the "id" does not match the currently logged-in user's id, resulting in all users except the one we logged in as.

Now that we have a list of users to chat with, let's quickly allow selecting them. We'll add a simple state variable to the App component to keep track of the user we've currently selected:

// add this import so we can make TypeScript happy
import type { User } from 'ihp-backend';

// add this to the App component
const [selectedChat, setSelectedChat] = useState<User | null>(null);

Let’s add a onUserSelect prop to the Users component which is called by an onClick handler on the button tag:

function Users({ onUserSelect }: { onUserSelect: (user: User) => any }) {
    ...
            <button
                className="btn btn-link"
                onClick={() => onUserSelect(user)}
            >
    ...

Now we can pass the setSelectedProp function to the Users component with that prop:

// replace this line in the App component
<Users/>
// with this one
<Users onUserSelect={setSelectedChat}/>

Now the App component keeps track of the user we're chatting with!

Minute 6: Allow sending messages to users

Next, let's create the Chat component, which we'll eventually use to chat with another user; for now, we'll just use it to display the currently selected user.

Create a Chat function component that accepts a user prop of type User and renders a simple div containing the user’s email:

function Chat({ user }: { user: User }) {
    return <div>
        {user.email}
    </div>
}

Let’s render that component from our App component by adding it below the Users component if the selectedChat isn’t null, and pass the selectedChat to it:

function App() {
    const [selectedChat, setSelectedChat] = useState<User | null>(null);

    return <IHPBackend requireLogin>
        <div className="container">
            <AppNavbar/>
            <Users onUserSelect={setSelectedChat}/>
            {selectedChat === null ? null : <Chat user={selectedChat}/>}
        </div>
    </IHPBackend>
}

When clicking on the different users, the email below the list should now change in the browser.

Let’s change the markup a bit to render the Chat component on the right side next to the Users:

function App() {
    const [selectedChat, setSelectedChat] = useState<User | null>(null);

    return <IHPBackend requireLogin>
        <div className="container">
            <AppNavbar/>
            <div className='row'>
                <div className='col'>
                    <Users onUserSelect={setSelectedChat}/>
                </div>
                <div className='col'>
                    {selectedChat === null ? null : <Chat user={selectedChat}/>}
                </div>
            </div>
        </div>
    </IHPBackend>
}

Things should now look something like this:

Now that we have a Chat component with access to the user we've selected, we can finally create the necessary code to send messages to that user.

Let’s add a form element inside the Chat component with a simple input and a submit button, which we can use to send messages:

function Chat({ user }: { user: User }) {
    return <div>
        {user.email}
        <form className="input-group mt-4">
            <input
                type="text"
                className="form-control"
                placeholder="Type a message..."
                aria-describedby="send-button"
                autoFocus
            />
            <button type='submit' className="btn btn-primary">Send</button>
        </form>
    </div>
}

I have added a bit of simple markup to make it look prettier.

// add this before the return in Chat:
function handleSend(event: FormEvent<HTMLFormElement>) {
      event.preventDefault();
      const input = event.currentTarget.elements.namedItem('message') as HTMLInputElement;
      // this is where the magic happens:
      createRecord('messages', {
          recipientId: user.id,
          content: input.value,
      });
      input.value = '';
  }

The important call here is the one to createRecord. IHP Backend provides this function. The first argument tells IHP Backend to create a new record in the messages table, and the second argument contains all the required fields we need to set for the record to be complete (it'll use the default values if we don't override them). Since IHP Backend uses the currently logged-in user's id as user_id by default (as defined in the schema) and generates a new id for the message automatically, we only need to set the recipient_id to the id of the user we've selected to chat with, and the content to the input's value.

Minute 7: Display sent messages

There's only one problem: once we send the message, there's no way to read it!

So the next step is to display all messages sent into the current chat.

To do so, we'll write another query using useQuery inside the Chat component. Let's start simple and get all messages the user has access to:

const messages = useQuery(query('messages'));

We can display this list of messages by adding these lines above the form tag and below the {user.email} line:

{messages?.map(message =>
    <div
        key={message.id}
        className={'message ' + (message.userId === getCurrentUserId() ? 'from-me' : 'to-me')}
    >
        <div className='message-content'>
            {message.content}
        </div>
    </div>
)}

For the CSS classes to do anything, add the following styles to public/app.css:

.message.from-me {
    text-align: right;
    padding-left: 2rem;
}

.message.to-me {
    padding-right: 2rem;
}

.message .message-content {
    border-radius: 5px;
    margin-top: 1rem;
    padding: 0.5rem;
    display: inline-block;
    text-align: left;
}

.message.to-me .message-content {
    background-color: lightgray;
}

.message.from-me .message-content {
    background-color: lightblue;
    right: 0;
}

I won't go over this in detail; it just makes things look a bit better. Feel free to take a closer look if you want, though.

After changing the CSS, you might have to reload the app in the browser to see the effects.

const messages = useQuery(
        query('messages')
                .where('userId', getCurrentUserId())
);

That still doesn’t limit the messages to those sent to the selected person though, so we’ll add another .where condition based on the recipient:

const messages = useQuery(
    query('messages')
        .where('userId', getCurrentUserId())
        .where('recipientId', user.id)
);

Multiple where conditions like this will be combined using AND.

Now we have all of the messages we sent, but we’re now missing the messages we received. To fix that, we can add a set of conditions using .or:

const messages = useQuery(
    query('messages')
        .where('userId', getCurrentUserId())
        .where('recipientId', user.id)
        .or(
            where('userId', user.id)
            .where('recipientId', getCurrentUserId())
        )
);

.or takes a list of conditions just as you can add them to query('messages'). You might have to add an import for where to the import list of ihp-backend at the top of the file.

.or uses all previous conditions for the left side of the resulting OR condition. If you want a bit more clarity, you can wrap the initial conditions with a single call to .where:

const messages = useQuery(
    query('messages')
        .where(
            where('userId', getCurrentUserId())
            .where('recipientId', user.id)
        )
        .or(
            where('userId', user.id)
            .where('recipientId', getCurrentUserId())
        )
);

I, personally, don't think that's necessary, though.

const messages = useQuery(
    query('messages')
        .where(
            where('userId', getCurrentUserId())
            .where('recipientId', user.id)
        )
        .or(
            where('userId', user.id)
            .where('recipientId', getCurrentUserId())
        )
        .orderBy('createdAt')
);

And finally, the correct messages show, in the proper order!

Minute 8: Realtime

We haven't done anything to make our app realtime yet... But the useQuery hook is realtime by default, meaning we don't have to do anything! IHP Backend will push new data to each client who requires it over a WebSocket connection. You can quickly try it out by opening a new private window in which you sign in as another user, sending messages between clients - the messages will show up in each browser without requiring a reload of the page!

I guess we can use this time for doing something else then.

Minute 8b: Commit and push (deploy)

Now that we've finished the frontend let's deploy it to production. Commit all changes and push them to your repository:

git add app.tsx public/app.css package.json package-lock.json
git commit -m "implement realtime chat"
git push

Vercel will notice a change on the main branch of our repository and deploy the changes automatically.

Enjoy your new app and possibly spare time!

Moving on

From here, you can continue playing around with IHP Backend. Maybe you want to allow users to set a different display name instead of displaying their email? Maybe you want users to request a chat with others, so they can't just send messages to anyone willy-nilly? Perhaps you want to implement group chat functionality?

What will you build with IHP Backend? Tell us in the comments!

Haskell as an alternative to TypeScript

digitallyinduced — Wed, 11 Aug 2021 11:20:33 +0000

If you've been using TypeScript for your web development, you have understood the value that static typing brings to your productivity. However, TypeScript still has some issues in regards to type safety. This article is supposed to show these issues and help you see how another statically typed language - Haskell - is solving them. In the end, I hope that you will have learned something, and might be interested in continuing your journey into type-safe programming by trying out Haskell for your next project. If you choose to do so, I recommend using IHP, a productivity-focused web framework with which you can build full-stack web-apps (but APIs work just fine as well).

The anti-pattern that is `any`

The any type included in TypeScript can cause many issues, as it straight up disables typechecking for whatever it's used for. Once you use it, you might as well write plain JavaScript. But it might actually be worse than that: people might be highly confident in their refactoring or new code if they don't get any type errors. What they might not notice is that an any somewhere else in the code where they didn't change anything is not throwing a type error, although it would if the correct type were used.

So why would anyone use any? I think there's a few different reasons:

the correct type is not known to the developer at the time of writing,
the correct type would be too complex, or
it's implicitly used by TypeScript because it can't figure out the correct type by itself (this one can be disabled using the noImplicitAny setting)

Now, if the correct type is not known by the developer, that could either mean it'd be useful for them to do some research into what it actually is, or, more likely, the type cannot be known at that point in time. In any case using TypeScript's unknown type is much better, as that is a type-safe way of accepting any value, that also disallows any interaction with the value that might be problematic. This is the type to use in case of migrating an existing JS codebase to TypeScript, as it keeps the guards of TypeScript intact.

If the correct type is too complex for the developer to figure out or to bother typing, and TypeScript isn't able to do so either, there's little you can do except use unknown again, which definitely isn't ideal. The developer probably already understands things about the type, but using unknown means that TypeScript will not, which will just lead to unnecessary checks.

In case Haskell was used instead, the likelihood of Haskell figuring out the type by itself (this is called type inference btw) is much higher. This is because in Haskell any isn't even an option, so it can't confuse the compiler. But also, ghc - the most widespread Haskell compiler - has years and years of effort behind it. And lastly, as long as you stick to basic Haskell, it is specifically designed to enable type inference.

Limitations of being a super-set of JavaScript

TypeScript has the core design-goal of being a super-set of JavaScript. What that means is that any JavaScript code is valid TypeScript code as well (if the transpiler is configured to accept it), and you only need to add code to add more definitive types to the code. This is great if you need to convert an existing codebase from JavaScript to TypeScript, as it allows you to work in very small increments.

The problem is that new projects built using TypeScript still suffer from many of the problems of JavaScript:

difficult-to-understand behavior that doesn't behave like in other languages (for example the this keyword)
many things on https://wtfjs.com/ ...and probably more.

So while I applaud converting an existing JavaScript codebase to TypeScript, I would never start a new project in either if there's good alternatives, which there always are for backend development. Also, using the right tools the need for a lot of frontend code can be eliminated, while maintaining a highly-interactive webapp. Check out IHP for my favorite solution right now.

Being a super-set of JavaScript, many type definitions are a lot more complex to write than they would otherwise need to be as well. Check out the following examples, which are type definitions for equivalent Haskell and TypeScript code:

// A function that takes a tuple of two values and returns the first:

// TypeScript
type first = <A, B> ([a, b]: [A, B]) => A

// Haskell
first :: (a, b) -> a

// a map function for lists/arrays

// TypeScript
type map = <A, B> ((a: A) => B, list: A[]) => B[]

// Haskell
map :: (a -> b) -> [a] -> [b]

TypeScript can't type everything

If you're using TypeScript you see the advantages of having static typing available, so we don't need to go over them. As such, it should bother you whenever you cannot actually use static types to encode useful information. Here are a few cases in which TypeScript cannot actually fulfill its promise of type-safety, and the way that Haskell solves it.

Side-Effects

If you've been following recent trends in software development, especially in the JavaScript world, you know that functional programming principles are becoming more and more popular. React is built on them! One of the things people are advocating for are "pure functions": functions that, given the same arguments, always return the same result and that don't have side-effects. What makes these functions so great is that they are very easy to reason about, and there are various techniques for performance optimization that are much easier using them, if not impossible without them.

When coding in TypeScript, figuring out whether or not a function is pure requires you to read its source code and figure out how it works, which might lead to other functions that you have to do the same thing for. This gets tedious and could easily be avoided if the information of function purity was included in the function's type.

In Haskell, this is done by making every function pure by-default. Whenever you need to have a side-effect in a function, you need to declare this on the type-level. Not doing so is a compiler error.

Failures

As long as everything works as expected, TypeScript works just fine. However, when something goes wrong, you will likely have to interact with an error that gives you more information. Before you can even do so though, you need to be aware that an error can occur - and this is one of the shortcomings of TypeScript. It is impossible to declare on the type-level that a function might throw an error. This means you still need rigorous testing to figure this out, and even then you might run into unhandled errors in production due to not having tested thoroughly enough.

In Haskell it is most common to force handling errors by making the return type include the information of whether or not the function succeeded or not. Depending on the actual function, you might get no, some, or a lot of information in case of a failure, but you can be sure that you are handling these cases. The two most common ways of representing the option for failure are the Maybe and Either types.

The Maybe type can represent success and failure by containing the success value in the success case, or Nothing in the case of a failure. This is also basically Haskell's way of handling null and undefined, which prevents from using these values in a way that they don't support, which might cause issues.

The Either type works in a very similar way: in the case of a success it simply contains the value that the function would return anyways. But in case of a failure it contains some other value. The type of this is clearly defined, which means that there's no ambiguity in how to handle it.

What's best about these techniques is that it does not only allow you to handle the error case in a type-safe fashion, it forces you to handle error cases where they might occur. If the function doesn't force you to handle the error case, no error can occur.

One place where typing the failure state should clearly be possible are promises, however TypeScript has no default way of doing this, which means that in case you run into a failure in your asynchronous code, TypeScript is not going to help you in figuring out the value you got in place of the success value.

Conclusion

TypeScript is a great way to improve an existing JavaScript codebase, and to bring a bit more productivity and safety to your frontend code. However, the language has issues, some of which are so ingrained in the language itself that they are not going to be solved with time. So whenever you can, try opting for a language that has less design issues at its core, such as Haskell, and avoid writing JavaScript/TypeScript wherever possible.

To allow you to do this, we at digitally induced have written IHP - an opinionated full-stack web framework based on Haskell, with a focus on developer experience and productivity, without sacrificing user experience. To try it out for your next full-stack project or backend, get started using the Guide and join our community forum or active slack workspace to get any support you might need. We try to help wherever we can.

Do you have any thoughts on TypeScript that you want to share? Did I miss anything? I'd love to hear your opinions and thoughts!

How IHP uses Haskell's Type System to enforce good patterns

digitallyinduced — Wed, 04 Aug 2021 12:56:30 +0000

Good patterns and clean code are what differentiates a production application from a legacy application. In a lot of cases, many production applications become legacy applications with time, because patterns aren't enforced and therefore ignored, wrongly interpreted, or otherwise abandoned.

IHP uses Haskell as its language of choice, and one big reason for this is the typesafety that Haskell provides. After reading this article you'll hopefully understand how IHP is making use of Haskell's strong typesystem to enforce proper use of patterns shared between all IHP applications, which prevents your production webapp from becoming a legacy webapp.

Sidenote: at digitally induced we have multiple older IHP apps, none of which we consider "legacy", even if they've been running for quite some time. If we need to make changes to them, it is very easy to get back into them and understand what is going on, as all IHP apps follow similar patterns. We know what to expect, and where to find the code we're looking for.

Model-View-Controller

Let's get the biggest point out of the way first. IHP uses the popular Model-View-Controller pattern, which is characterized by the three parts giving the pattern its name:

The Model is the data of the application, which has a static structure when running, but variable content, as the content is user-generated. In IHP all data types are auto-generated from the database schema, ensuring that the code you write is always compatible with the database.

The View is a simple mapping that turns data into Html. Using Haskell's type system, this is enforced by defining every view as a pure function (a function without side-effects that always produces the same output if it receives the same input). You might have heard that that's the core idea of React as well, and it's a reason React is so popular: the render function should simply take the current component's state and render Html based on that. However, React has the problem that everything else is also possible in the view, and in a way even requires it to be there, including updating state. In IHP, the view really fulfills this promise, and it's enforced by the type system.

The Controller is the part of the application that contains the actual business logic, and should be the only place in the application that is able to interact with the outside world, including the database (also known as IO: Input and Output). In Haskell, doing IO isn't possible everywhere, only in functions that have been declared to be able to do it. IHP makes use of that by defining the actions (endpoints of controllers) as the only functions that can run IO things. Even if someone is tempted to fetch data from the database in the View, they can't, because the controller is simply going to prevent it from working.

Fetch all required information

As described above, the View is a function mapping data to Html. However, this data is different from view to view of course. Since the data has to be fetched by the controller, the view defines a data structure which the controller needs to completely fetch the information for to render the view, which makes sure that no information is ever missing in the view, not even accidentally. And when some information is not necessary anymore, you can just remove it from the view data structure, which will cause compiler errors everywhere where you're still fetching it (where there could now be unnecessary code).

To read more about how passing the data from controller actions to the view works, read the documentation here.

No missing information for links

When the user wants to interact with the website, they mainly do so via links. Usually links are simply strings, which means that if parameters are required but missing, this can only be detected via trial-and-error. Using IHP's pathTo and urlTo functions, you can build the links between pages of your application in a typesafe way, which means you're not going to forget to send new necessary information when an endpoint requires it, and will not forget to remove it when it's unnecessary anymore. Renaming is a non-issue as well, and typos are (again) compiler errors.

IDs cannot be used to query the wrong database table

In IHP, IDs are (by default) UUIDs. But even if you use Integer-based IDs instead, you could run into a situation where you'd accidentally use a user-ID for querying a different table, and wouldn't be any wiser, since both are UUIDs. In IHP on the other hand, all IDs are wrapped once more, making the type of the ID Id User for example. You then can't use this ID to for example fetch a product.

If for some obscure reason you still need to do this, or you get the ID as another type and need to convert it to this special type, that's of course possible.

This special type also allows the fetch function that queries the database for a single row with the given ID to be super simple to call: since the ID already contains the information of which table it's for, you don't have to do any more work than passing the ID to the function, and it will take care of the rest.

Ensuring proper HTML

Views in IHP are written in Haskell, using something called HSX, which is the same basic idea as JSX in React. That means you write the HTML you would normally write, and can easily include dynamic Haskell code where needed.

Since HSX is just syntactic sugar for other Haskell functions though, it is typesafe! That means you can't use attributes for elements where the spec doesn't allow for it, and many markup errors (like forgetting to close a tag) are caught at compile-time.

If you need to use custom attributes, that's what data- attributes are for, and they are fully supported. Just like custom web components.

Bonus: beginners in React often want to quickly output the content of some data they have, and try to just inline the variable in their JSX. They are then often surprised to see [Object object], since converting an object to a string in JS will lead to this result. In HSX, this will call show on the provided data if possible, leading to the expected result.

`Maybe` and the dreaded `NullPointerException` (or `TypeError: variable is undefined`)

While technically not IHP-exclusive, null and undefined do not exist in Haskell. Instead, if you need to represent something not being there, you can use Nothing, which is a value for the Maybe type. Using this, you can represent that something might not be there, which will force you to handle that case. But once you've handled that case, you don't have to handle it again - something that I've seen a lot in medium to larger codebases, where it's not always entirely clear where a value might come from.

What this means in essence is that you will never get a NullPointerException or a TypeError: yourVariable is undefined when using IHP!

Conclusion

IHP makes as much use of Haskell's types as possible, leading to less bugs and an easier-to-grasp codebase that won't become legacy. If this article peaked your interest in IHP, you can get started using the Guide.

Displaying Real-Time Data in Your Web Application Without Hassle: IHP Auto Refresh ✨

digitallyinduced — Thu, 15 Jul 2021 06:42:59 +0000

In the IHP framework we have one feature that typically looks like dark magic to people coming from other frameworks: Auto Refresh ✨. Ever wanted to display real-time data in your web application, but found WebSockets too much of a hassle? Add a single keyword in your IHP controller, and you are all set.

Auto Refresh offers a way to re-render the HTML views of your application when the underlying data changes, as long as the page is still open inside the user’s browser window. Auto Refresh replaces manually polling for status updates or complicated Websocket code.

Without any manual work we can have e.g. live updating dashboards, chat message views that automatically display new messages when they arrive, or news feeds that automatically display new activities.

If you have a react.js background, you can think of an Auto Refresh view as a react component where the state is the actual backend PostgreSQL database. Whenever the database state changes, the view is re-rendered. Like a normal react component. The only major difference in our approach is that all the rendering is happening on the server side. So you have access to all your application code.

Real-world example: IHP Cloud

IHP Cloud is a deployment platform for IHP applications. After clicking on the “Deploy now” button, the user is redirected to a deployment status page. Similar to GitHub actions you can see the current status of the deployment and all the logs. Once the deployment is finished, the status turns green.

Before IHP Auto Refresh was invented, this page was implemented using a manual ajax polling every 1 second. This was very error prone and polling too fast sometimes caused the CPU coolers to turn on.

Here’s how it looks now with Auto Refresh:

The progress bar, logs and the deployment status is automatically updated without any app-specific javascript. Whenever the deployment progresses, the IHP server pushes an updated view to the browser.

Auto Refresh can be activated for any IHP controller action by adding a single autoRefresh keyword in front of the action.

Here’s the code of the above deployment status view:

You can see that there’s an autoRefresh keyword in front of the “do” in the first line of the action. This enables auto refresh. This single keyword is all it needs for IHP auto refresh to get going.

If we would remove the autoRefresh keyword, we would need to manually refresh the page all the time to see the latest deployment status.

Let’s take a look at what IHP’s autoRefresh keyword does.

IHP Auto Refresh: Technical Overview

When we first load a page like the deployment status page above, the autoRefresh keyword activates IHP Auto Refresh for this action. Once activated it starts tracking all SQL queries the controller action is running against the database. It inspects the SELECT * FROM … queries and keeps track of all the tables that have been used.

After the page is initially rendered on the browser, a small JavaScript function provided by IHP will connect back to the Server using a WebSocket connection.

When the WebSocket connection is established, IHP starts watching the tables your action has been using for changes.

In our example view from above, it starts watching on the deployments and deployment_logs tables, as these have been used for rendering the initial deployment status page.

Now a job worker starts working on the deployment. It will insert new log lines into the deployment_logs table and at the end update the deployments table to mark the deployment status as completed.

Whenever IHP auto refresh is notified about a table change via pg_notify, it will re-run the action on the server-side. When the generated HTML looks different than the HTML generated on the initial page load, it will send the new HTML to the browser using the WebSocket connection.

Whenever the JavaScript on the browser-side receives new HTML, it will update the current page using a DOM-diff approach (using morphdom). So only DOM nodes that have actually changed between the initial page load and the updated HTML will be updated.

All of this happens behind the scenes.

Summing things up:

Auto Refresh is a very handy tool to make “live” views that always display the latest data. It can replace most needs for manual ajax polling or complicated WebSocket update code. Because it’s so quick to set up, you typically end up using auto refresh in places where you otherwise wouldn’t add any auto-update logic, when you’d have to manually write it.

If you're new to IHP, check out the demo video 📺.
You can learn more about IHP Auto Refresh in the documentation 📚.

Two Quick IHP tips to dynamically assign classes

digitallyinduced — Fri, 09 Jul 2021 07:28:42 +0000

Here are two quick tips for IHP:

Use the classes helper

...to dynamically assign classes to elements in your views. It's an easy way to simplify your code by a lot:

-- BEFORE
<a class={usersLinkClasses} href={UsersAction}>Users</a>
<a class={invitesLinkClasses} href={InvitesAction}>Invites</a>
...
where
    usersLinkClasses = "nav-link" ++ if isActivePath UsersAction
        then " active"
        else ""
    invitesLinkClasses = "nav-link" ++ if isActivePath InvitesAction
        then " active"
        else ""

-- AFTER
<a class={classes ["nav-link", ("active", isActivePath UsersAction)]} href={UsersAction}>Users</a>
<a class={classes ["nav-link", ("active", isActivePath InvitesAction)]} href={InvitesAction}>Invites</a>

Use `isActivePathOrSub` instead of `isActivePath`

If you read the previous example, you might have noticed that I used isActivePath to dynamically assign the active class to the links. Well, using isActivePathOrSub this will also work if the path is a sub-path. In the following example, both /Settings and /Settings/Profile would match and cause the link to get the active class. Learn more in the documentation.

<a class={classes ["nav-link", ("active", isActivePathOrSub "/Settings")]} href={SettingsAction}>Settings</a>

If this peaked your interest, get started with IHP now and tell us what you think!

IHP v0.11.0 brings Server-Side Components and Joins!

digitallyinduced — Thu, 17 Jun 2021 09:00:21 +0000

We've just released IHP v0.11.0, which includes:

Server-Side-Components, similar to React or elm
Joins, for more complex queries
IHP.FileStorage, which makes it easy to store files on AWS S3 or any other compatible service
...and more!

Server-Side-Components aka. you don't need React

IHP's new Server-Side-Components allow you to build React-like components on the server (as the name implies). This allows you to build highly interactive pages without having to worry about server vs. client state, and no change of environment - as everything is still in Haskell.

Let's look at an example component, a basic counter:

-- everything starts with the normal module definition and imports
module Web.Component.Counter where

import IHP.ViewPrelude
import IHP.ServerSideComponent.Types
import IHP.ServerSideComponent.ControllerFunctions

-- Followed by a type definition for the state.
-- This means there will never be any surprise what the state contains.
-- In this case it's simply an Int, so a number.
data Counter = Counter { value :: !Int }

-- Then comes a list of possible actions that can be used to update the state.
-- If you've used redux or the elm architecture, this should be familiar.
-- Defining what actions are available means it's there won't be any surprises here either, and future developers can immediately see what behavior this component supports.
data CounterController
    = IncrementCounterAction
    deriving (Eq, Show, Data)

-- just one line of boilerplate to generate some code that we really don't want to write ourselves...
$(deriveSSC ''CounterController)

-- The heart of any component are
-- 1. the render function, taking care of turning the state into html
-- 2. action handlers, which update the state based on selected actions
instance Component Counter CounterController where
    -- but first, we need to define the default state
    initialState = Counter { value = 0 }

    -- the render function takes the state and return HTML
    render Counter { value } = [hsx|
        Current: {value} <br />
        <button onclick="callServerAction('IncrementCounterAction')">Plus One</button>
    |]

    -- this is the handler for the IncrementCounterAction
    -- the function takes a state and the action, modifies the state (in this case incrementing the counter's value) and returns the new value
    action state IncrementCounterAction = do
        state
            |> incrementField #value
            |> pure

-- this allows us to use 'incrementField' to increment the counter
instance SetField "value" Counter Int where setField value' counter = counter { value = value' }

And the result is a beautiful counter, all controlled server-side:

Here's a little gif showcasing a more complex use-case of a filterable and sortable table:

To learn more check out the documentation.

Joins

If you've tried to do complex queries involving joins of multiple tables in IHP, this was previously a little bit of a hassle. With first-class support for joins, there's now a completely type-safe way to do anything you can imagine.

Here's an example of how you can select all posts that were written by a user with the name "Tom":

tomPosts <- query @Post
        |> innerJoin @User (#authorId, #id)
        |> filterWhereJoinedTable @User (#name, "Tom")
        |> fetch

And here's a more complex example that selects all posts that were tagged by a tag named "haskell" in the case of a many-to-many relationship:

query @Posts
        |> innerJoin @Tagging (#id, #postId)
        |> innerJoinThirdTable @Tag @Tagging (#id, #tagId)
        |> filterWhereJoinedTable @Tag (#tagText, "haskell")
        |> fetch

IHP.FileStorage to store files in AWS S3-compatible services

Instead of having to manually use the APIs of AWS S3, you can now use our special support for these services to upload anything you'd like.

Check out this example for an action used to upload a logo of a company to S3:

action UpdateCompanyAction { companyId } = do
    company <- fetch companyId
    company
        |> fill @'["name"]
        |> uploadToStorage #logoUrl
        >>= ifValid \case
            Left company -> render EditView { .. }
            Right company -> do
                company <- company |> updateRecord
                redirectTo EditCompanyAction { .. }

As you can see it's not much different from any other action used to update the company data. All the magic happens due to one line: |> uploadToStorage #logoUrl.

You can do much more though, for example:

use ImageMagick to do pre-processing of the uploaded image file (resizing, conversion,...)
generate secure, signed download URLs for private files
in development, files are stored on-disk in the static/ folder for ease of debugging and offline-only development

Find out how to use it and configure it for your project in the documentation.

Case Insensitivity

We've added filterWhereCaseInsensitive and validateIsUniqueCaseInsensitive, which do exactly what you expect them to do.

If you're using IHP's login, be aware that these functions are now used for checking the emails. This increases UX for your users, but in case someone messed up and created two accounts - one with some letters of their email uppercase, one not - you will have to migrate that account.

Conclusion

If you haven't tried out IHP yet, now's a great time to do so. We'll be at ZuriHack (huge Haskell Hackathon), so sign up for free there if you haven't already and get an introduction to IHP from us directly!

Why you should use IHP instead of express

digitallyinduced — Wed, 03 Mar 2021 10:29:45 +0000

express is one of the most popular options for writing webapps these days. IHP on the other hand is the fastest growing Haskell web framework.

If you've been using express, this article is supposed to give you an intro into all of the good stuff you might be missing out on.

Live Reloading

express and related tooling are notoriously known for the fact that to start any project, one will first have to do a lot of configuring to get nice developer tooling set up, but also to get everything running at all.

IHP works on a different ideology: at digitally induced, we aim to make software engineering feel magical again. As such, configuration is turned down to a minimum, while providing the best developer tools out-of-the-box.

One such tool is live reloading. While you can get some form of automatic server restarts on file save set up with express, it'll take a while to configure everything properly. And in the end, states will likely not be preserved. Additionally, and webpage that's been opened that requires reloading will have to be reloaded by hand (unless you want to spend multiple hours with configuration again).

When using IHP, all of that is done for you. Whatever you change - whether that's frontend code, or backend code - it'll only require you to save the file for you to see the result in your browser, as the included developer tools reload everything for you. Even better, the website doesn't even have to do a full reload - instead, only the parts of the page are updated that actually need updating.

Websockets and Auto Refresh

So live reload is great for developing, but there's a similar situation in production apps too: if the data on the server changes, we might want to update what's shown in an already opened website. When using express, you'll have to do some ajax to get that to work.

With IHP, all the necessary tools are included to set up a websocket connection to the client very easily. If you happened to build a webapp using express instead, you'll have to pick up a second library for that, and coordinate between the two.

However, since most websocket connections are used for the same thing (updating what the client sees based on changing information from the server), IHP makes it even simpler for developers: it's got auto refresh.

By simply setting an action (the equivalent of a route) to have auto refresh enabled, any changes will be pushed to all open clients via a websocket connection whenever the database has updated data for the relevant page.

It'll literately require you to do nothing more than type autoRefresh before the code of the route. That's 11 letters. And you're done.

Code generators

Speaking of saving keystrokes: in projects there tends to be some amount of boilerplate. And that's really annoying to type. With IHP, typing boilerplate is a thing of the past. Code generators allow you to generate everything that's not specific to your implementation, which means it takes seconds to get set up for new features.

If you use the web ui instead of the CLI to do the code generation, you even get nice syntax-highlighted previews of what will be generated, so you can make sure everything works as expected. But honestly, I've never had a case where it didn't do what I wanted it to.

Functional Programming

JavaScript is seeing a big move towards the paradigm of functional programming. Routes are simply functions in express, React is is defaulting to function components, and functions like filter, map and reduce are all becoming more and more popular.

Since IHP uses Haskell - a purely functional programming language - you get all of that goodness too. Only better, because it's the whole concept of Haskell.

Being purely functional has other advantages than just being trending though. Pure functions do not have side effects. When something does go wrong, it's really easy to find out where to look for the error, because there's only a handful of places the bug could hide. While in express it could be nearly everywhere. The reason for this is that reasoning about the things a function does by just looking at its type signature is really easy. Speaking of which...

Type-safety

JavaScript is a weakly and dynamically typed language. Haskell on the other hand is strongly and statically typed. That means that while JavaScript allows you to use any variable everywhere (even one that hasn't even been created before), Haskell will make sure that whatever variable is being used, makes sense at that place.

Lots of people will say that dynamic and weak typing have advantages, and that's certainly true - there's definitely situations in which it is advantageous. But in most cases, there's only a limited subset of values that make sense, and that's where strong, static typing will prevent a whole host of bugs. Just look at the popularity of typescript, which attempts to bring strong, static typing to JavaScript. Since it's tacked-on it isn't as expressive as Haskell's type system, which has been developed for years and years already.

If you're a Javascript developer and find writing typescript code annoying, I fully understand you. While typescript is great in its idea to bring strong, static typing to the web, it is lacking good type inference. That means that most people will have to write long, complicated type definitions by hand. In most cases Haskell will infer the type for you, meaning you get all the benefits, without the costs.

The result is a language that will show you lots of bugs before you even run your code. You see lots of people saying they'd rather have code not compile for hours, instead of compiling and having to hunt down unnoticed bugs for days. And that's exactly what Haskell can do for you. Just try it, and you'll learn to love the compiler.

Faster performance thanks to Haskell green-threads

Speaking of compiling. It's well-known that compiled languages tend to be faster than interpreted languages. That is another reason to use IHP, as Haskell will make your web app faster without you having to do anything, just because you use Haskell. Since express is running on Javascript, which is an interpreted language, it's very hard to get a get performance.

To increase performance, multithreading is a useful tool that allows a developer to get big bang for your buck. That is, if you're able to use it. Which you won't be if you use express, since Javascript is a single-threaded language.

Sure, there's async-await and promises, but everything still stays in one thread. Which makes reasoning about your program easy, but it doesn't allow you to get as performant as you otherwise could be.

When using Haskell, you have it much easier. Multithreading is already done for you. You won't have to reason about race conditions and all those complicated situations that could arise by using async-await. Instead, the Haskell compiler is smart enough to multi-thread the parts of your application using something called green threads, without you having to do anything - and you will not run into any reasoning issues because of it. It basically is a free performance boost!

Deployment

Due to its popularity, deploying express applications has never been easier. At digitally induced we understand that, which is why we've built ihp-cloud. It's as simple as creating a git repository and telling us where to find it, and your repository can be deployed.

Community

No doubt, express has a great community and lots of documentation. IHP's community is quickly growing too, however, and you'll always find help in our community slack at https://ihp.digitallyinduced.com/Slack, where we from digitally induced (the company behind IHP) will do everything to assist you in getting started with IHP and Haskell.

If you want to learn first-hand what the community of IHP is doing, feel free to join the first global IHP Meetup on March 17th, 2021 at 18:00 CET: Join IHP Global Meetup. We hope to see you there!

Conclusion

If undefined errors, configuration messes, hours of hunting bugs annoy you as much as it annoys us, now's the perfect time to try out IHP. Follow the Guide to get set up, build, and deploy your first web app in minutes - then tell us what you liked and where we can improve even further. We hope to see you on March 17th!

IHP v0.9 is out!

digitallyinduced — Mon, 01 Mar 2021 15:39:04 +0000

Better performance, new plugins, logging, websockets, more query builder functions and more!

On friday we released a new version of IHP - the productivity-focused, magical-feeling-inducing haskell web framework for the future!

To celebrate, here's the some of the awesomeness you can try out right now, after following the Getting Started Guide:

New plugins

While we're still developing the plugin API, we're already building some for you to use! This way we can make sure that the API makes sense and supports all use-cases. Now, with the new release, you can use these two new plugins with your IHP Apps:

ihp-sentry

Error reporting is vital to web app development, and sentry is a popular solution for this. As such, it's now easier than ever to integrate it into your IHP app. Check out the plugin's readme for details on how to get it running inside your IHP app: https://github.com/digitallyinduced/ihp-sentry.

ihp-zip

Sometimes your users want to download a lot of files at once. Especially with the DSGVO, users could always request all their data from your website. What better way to handle this than implementing a simple zip-download containing everything they ask for? Previously this might've been a hassle, but now with the new ihp-zip plugin, it's a breeze. Just like before, check out the plugin's readme for installation and usage instructions: https://github.com/digitallyinduced/ihp-zip.

WebSockets

IHP has always used websockets to update the frontend, and now you can easily use a custom websocket connection too! Just think of the possibilities: chat applications, real-time updates, games...

Of course, to get started you'll have to learn how to tap into this newfound power. Don't worry, we've got you covered: https://ihp.digitallyinduced.com/Guide/websockets.html.

Better Performance

Everyone loves themselves a faster server. It's best when you don't even have to do anything to get the benefits. So, IHP v0.9 uses GHC's new non-moving memory, which should improve performance of all those awesome IHP apps out there! (Not that there was a performance issue before... But faster is always better, isn't it?)

Logging

We've already talked about error reporting. However, logging is just as important. And IHP now has its own Logging module ready for you to use! Say goodbye to putStrLn, and say welcome our new overlords Log.debug, Log.info, Log.error, Log.warn, Log.fatal and Log.unknown! You can even customize what a single line of logging looks like. Check out the detailed documentation: https://ihp.digitallyinduced.com/Guide/logging.html.

Query Builder Functions

There's a whole bunch of these:

`withTransaction`

...allows you to run multiple queries in a single database transaction.

`setJust`

...so you can simply do project |> setJust #userId (get #id user) instead of project |> set #userId (Just (get #id user)).

`distinct`

To remove duplicate rows from your query results.

...and more!

Increased Magic

Yepp, you heard that right. Actually this is related to AutoRoute. You can finally use more than just UUIDs and Id Project-like arguments for your controllers, without having to manually configure parseArgument. This simply means: less boilerplate, more magic, more productivity! We wrote it, so you don't have to.

Conclusion

This release held a bunch of awesome things, and we're happy that it's finally out there. If you want to read up on all the other awesome things that changed, here's the link to the changelog on Github: https://github.com/digitallyinduced/ihp/releases/tag/v0.9.0.

If you still haven't checked out IHP, now's as good a time as any. Also, join us in our community Slack: https://ihp.digitallyinduced.com/Slack.

That's it! Tell us what your favorite feature of this release is, and till next time!

Haskell: The Good Parts

digitallyinduced — Wed, 24 Feb 2021 14:51:55 +0000

This post was originally published on October 29th 2020 on the IHP blog. Some tiny edits have made it into this version of the post.

There’s been a recent blog post "Haskell: The Bad Parts" in the haskell community. To keep things in balance and to spread some positive vibes we should also talk about the good parts of the haskell programming language and it’s ecosystem.

Here are some of the best parts we encountered while using Haskell at digitally induced. We focus on the advantages in the web dev space because that is what we are currently working on.

Type Safety

Haskell has one of the most impressive type systems of any programming language in practical use. If you have used TypeScript or other type safe languages in the past, you should be aware of the great advantages of having a type-checked codebase. Now think TypeScript - but 10x better. That’s how Haskell feels like.

You save a lot of time debugging runtime errors. Once the compiler approved your code, you can be pretty sure that it is working. This kind of development process is usually a lot more fun than debugging why something is null or undefined.

Once your system has hit a certain size and when new feature requests are rolling in, you will want to make changes and refactor some parts of your code base. With Haskell you feel empowered to make changes to any part of your codebase.

Compare this to the ruby ecosystem: When working with rails you usually need to have lots of tests or otherwise you cannot confidently refactor code after things are running in production. And even then: things will break. With the power of the type safety provided by Haskell, we can make refactorings whenever we want.

It really is a blessing.

Managed Side Effects

The way you deal with the file system, external APIs and user input is way different in Haskell than in other less functional programming languages. Your program consists of a main routine that handles the side effects and calls all your pure functions that do the real business logic.

Systems built this way scale really well because there are less moving parts. Additionally, pure functions can be easily tested and changed later on.

Most other languages encourage you to do side effects in an unrestricted way. For example: when working in Java, a call to an object method might indirectly change the state of many related objects. This means you cannot easily reason about what a method call does. In Haskell most functions are pure and thus don't trigger side effects like this. And when they do, you can see this already by the function's type signature.

Haskell forces you to manage your side effects in a more careful way. You can still do IO and have mutable state, you just need to make this explicit inside the type signature. This leads to a far more robust system in overall.

Performance

Out of the box the performance of Haskell based web applications is great. It just feels faster than your typical Rails or PHP application. Thanks to its highly optimized runtime system it can also handle way more requests than a nodejs application.

And you get all that without ever thinking about performance at all.

Tooling

In 2020 it’s finally good. Thanks to Haskell Language Server (which just released version 1.0.0!) there’s now an easy way to have type information, documentation on hover and smart refactorings inside your text editor.

With nix, cabal and stack we have the best tools for managing Haskell dependencies. Cabal hell is a thing of the past.

Great things are also happening to the Haskell compiler itself. We can soon write dot expressions as you know from most other programming languages: project.name instead of name project.

Hiring Haskell Developers

Haskell is a secret super power in that regard. The Haskell community consists of many very smart and talented software engineers. Haskell developers usually learn about Haskell because they care about their craft and about building high quality software products instead of learning about it to get a high paying job. Exactly the kind of people you want in your team.

2020 Haskell is Ready for Prime Time

For years there has been this trend of growing use of type safety as well as the growing use of functional programming techniques. What language could fill this space better than Haskell. Haskell has really matured in the last years and in 2020 it feels like it’s finally ready to conquer the world.

If this post made you interested, check out IHP, our batteries-included haskell web framework.

IHP and elm - towards a functional web

digitallyinduced — Mon, 25 Jan 2021 15:34:48 +0000

At digitallyinduced we are working on IHP, the fastest-growing, open-source haskell web framework out there, because we believe functional programming to be the future. We want to make it accessible to everyone, even functional-programming-beginners!

To reach that goal, we have recently added an elm template, which allows you to get started with elm perfectly set up and ready to go in a new IHP project.

Getting Started

Getting started is as simple as installing the ihp-new command, and then running:

ihp-new --elm my-new-project

You'll get a fully set up IHP project with elm in a new folder called my-new-project. Check out the Guide to learn what to do with the project, including where to find the elm code (hint: it's in my-new-project/elm/ ;) ), and how to deploy the project for free using ihpcloud!

Try it out, and tell us how you like it!

DEV Community: digitallyinduced

thin.dev: Realtime-by-default BaaS (Backend-as-a-Service)

Preparation

Minute 1: Sign up for Thin Backend

Minute 2: Create the project

Minute 3-4: Modifying the schema

Minute 4: Cloning the Frontend locally

Minute 5: Listing users to chat with

Minute 6: Allow sending messages to users

Minute 7: Display sent messages

Minute 8: Realtime

Minute 8b: Commit and push (deploy)

Moving on

Build and deploy a real-time react chat app in under 10 minutes

Preparation

Minute 1: Sign up for IHP Backend

Minute 2: Create the project

Minute 3-4: Modifying the schema

Minute 4: Cloning the Frontend locally

Minute 5: Listing users to chat with

Minute 6: Allow sending messages to users

Minute 7: Display sent messages

Minute 8: Realtime

Minute 8b: Commit and push (deploy)

Moving on

Haskell as an alternative to TypeScript

The anti-pattern that is any

Limitations of being a super-set of JavaScript

TypeScript can't type everything

Side-Effects

Failures

Conclusion

How IHP uses Haskell's Type System to enforce good patterns

Model-View-Controller

Fetch all required information

No missing information for links

IDs cannot be used to query the wrong database table

Ensuring proper HTML

Maybe and the dreaded NullPointerException (or TypeError: variable is undefined)

Conclusion

Displaying Real-Time Data in Your Web Application Without Hassle: IHP Auto Refresh ✨

Real-world example: IHP Cloud

IHP Auto Refresh: Technical Overview

Summing things up:

Two Quick IHP tips to dynamically assign classes

Use the classes helper

Use isActivePathOrSub instead of isActivePath

IHP v0.11.0 brings Server-Side Components and Joins!

Server-Side-Components aka. you don't need React

Joins

IHP.FileStorage to store files in AWS S3-compatible services

Case Insensitivity

Conclusion

Why you should use IHP instead of express

Live Reloading

Websockets and Auto Refresh

Code generators

Functional Programming

Type-safety

Faster performance thanks to Haskell green-threads

Deployment

Community

Conclusion

IHP v0.9 is out!

New plugins

ihp-sentry

ihp-zip

WebSockets

Better Performance

Logging

Query Builder Functions

withTransaction

setJust

distinct

Increased Magic

Conclusion

Haskell: The Good Parts

Type Safety

Managed Side Effects

Performance

The anti-pattern that is `any`

`Maybe` and the dreaded `NullPointerException` (or `TypeError: variable is undefined`)

Use `isActivePathOrSub` instead of `isActivePath`

`withTransaction`

`setJust`

`distinct`