Keel + Remix
In this guide, you’ll learn how to quickly set up a Keel-powered application using the Remix full-stack web framework.
Create Remix project
Create a Remix project by running the command below:
npx create-remix@latestOn running the command, you’ll have to answer a few questions. Answer them as shown below:
Where should we create your new project? ./remix-guide
Initialize a new git repository? <Yes>
Install dependencies with npm? <Yes>After completing this step, you should have a remix-guide directory containing the Remix project. Now, navigate to that directory with the command below.
cd remix-guideBuild your backend with Keel
Keel utilizes a schema-driven approach to application development. This means that all you need to construct a fully managed backend is to define a schema comprising data models, APIs, and permissions.
In this guide, you'll learn to quickly set up a CRUD backend for a basic task manager.
The schema
Create a new file called schema.keel in the project root directory and insert the snippet below:
model Task {
fields {
description Text
}
actions {
create createTask() with (description)
get getTask(id)
update updateTask(id) with (description)
delete deleteTask(id)
list listTask() {
@orderBy(createdAt: desc)
}
}
@permission(
actions: [create, get, update, delete, list],
expression: true
)
}The schema above creates a Task model with a description field and some actions that let you interact with tasks over the API.
💡 All models have id, createdAt and updatedAt fields by default.
By default, your Keel APIs are secure unless you explicitly define permission rules to access them. For this example, the API permission is set to be accessible publicly (e.g., without auth) by setting a permission rule that always allows access using expression: true. Learn more about permissions in its dedicated page.
From this schema, Keel will create a fully managed API that can be used via JSON endpoints or GraphQL.
Keel supports running a local instance of your backend with Docker. Let's explore how we can get our backend up running locally.
Running your backend locally
Ensure Docker is running.
docker psWith Docker running, you can run the backend using the Keel CLI.
keel runYou should see a success message on your terminal and API endpoints to interact with your Keel backend. If it runs locally, it will run in the cloud. Let's look at how we can deploy it to the cloud.
Deploying your backend to Keel
Sign in to your GitHub account, create a repository, and copy the corresponding Git URL.
With that done, create a project on Keel by going to console.keel.so (opens in a new tab), select the Existing code option, input details, authorize GitHub, and select the repository you just created.
Next, add the Git remote URL to the Remix project.
git remote add origin <REPLACE WITH COPIED URL>With that done, push the code to the repository by running the commands below:
git add .
git commit -m "keel backend deploy"
git push origin mainOnce the repository is updated, Keel will use the schema to build and deploy your backend. In the Keel console (opens in a new tab), navigate to the API explorer tab, and all your actions will appear as API endpoints.
Integrate Keel with Remix
To use your Keel APIs in your Remix project, Keel can generate a fully type-safe API client based on your schema using the Keel CLI.
keel client .With that, you should see a keelClient.ts file at the root of your project.
Create a Keel client
A best practice with Keel when using the client on the server side is to create an instance of a Keel client per request to keep things isolated between requests.
This is because clients are stateful and contain an access token as part of their instances. If we share clients across server-side requests and requests may service distinct clients if a serverless function is warm and reused, then that presents a risk of leaking tokens between requests. Thus, it's safer to create clients and associate access tokens per request.
Create an app/utils/createClient.ts file to create and return a Keel instance.
import { APIClient } from '../../keelClient';
export const createClient = () => {
if (!process.env.KEEL_API_URL) {
throw new Error('KEEL_API_URL environment variable not set.');
}
const client = new APIClient({
baseUrl: process.env.KEEL_API_URL,
});
return client;
};Finally, create a .env file in the project root and add the Keel API root. Note that the URL should end with just /api.
# Using Keel in your local
KEEL_API_URL=http://localhost:8000/apiBuild a task management app
With the APIs running, let's utilize Keel in a basic task management application that supports creating and listing tasks.
Create the application components
Create an app/components/CreateTaskForm.tsx file and add the code snippet below. This code will use the Form (opens in a new tab) component to handle the form for creating tasks.
import { Form } from '@remix-run/react';
export const CreateTaskForm = () => {
return (
<Form method='post'>
<textarea
name='description'
cols={30}
rows={2}
placeholder='Enter task description'
required
/>
<button type='submit'>Create</button>
</Form>
);
};Finally, create an app/components/TaskList.tsx file to display the available tasks.
import { SerializeFrom } from '@remix-run/node';
import { Link } from '@remix-run/react';
import { Task } from 'keelClient';
type TaskListType = {
tasks: SerializeFrom<Task[]>;
};
export const TaskList = ({ tasks }: TaskListType) => {
return (
<ul>
{tasks.map((task) => (
<li key={task.id}>
<div>
<p>{task.description}</p>
<div>
<Link to={task.id}>
<p>Edit</p>
</Link>
<button>
<p>Delete</p>
</button>
</div>
</div>
</li>
))}
</ul>
);
};Note how on line 3 you can import the Task type from the generated client, making your app fully type-safe.
Putting it all together
Update the app/routes/_index.tsx file to include a loader to get the list of tasks and an action that the CreateTaskForm component will use to create tasks and render the components.
import {
json,
type ActionFunctionArgs,
type MetaFunction,
} from '@remix-run/node';
import { useLoaderData } from '@remix-run/react';
import { CreateTaskForm } from '~/components/CreateTaskForm';
import { TaskList } from '~/components/TaskList';
import { createClient } from '~/utils/createClient';
export const meta: MetaFunction = () => {
return [
{ title: 'New Remix App' },
{ name: 'description', content: 'Welcome to Remix!' },
];
};
//add a loader to get a list of tasks
export const loader = async () => {
const client = createClient();
const response = await client.api.queries.listTask();
if (response.data) {
const tasks = response.data?.results ?? [];
return json(tasks);
} else {
throw new Error(response.error.message);
}
};
//add an action to create tasks
export const action = async ({ request }: ActionFunctionArgs) => {
const client = createClient();
const formData = await request.formData();
const description = String(formData.get('description'));
if (!description) {
throw new Error('No description provided.');
}
const response = await client.api.mutations.createTask({ description });
if (response.data) {
return null;
} else {
throw new Error(response.error.message);
}
};
export default function Index() {
const tasks = useLoaderData<typeof loader>();
return (
<div>
<CreateTaskForm />
<section>
{tasks.length === 0 ? (
<p>No tasks yet!</p>
) : (
<TaskList tasks={tasks} />
)}
</section>
</div>
);
}Once completed, run the local server with the command npm run dev and test it on a browser using localhost:3000.
Next steps
Well done! You have successfully set up a Keel-powered application using the Remix full-stack web framework. You can extend the application further by adding custom CSS and support for updating and deleting tasks.
Check out the examples repository (opens in a new tab) with several real-world examples of using Keel with various frameworks and libraries.