Quickstart tutorial with Next.js #8269
Conversation
scotttrinh
changed the title
scotttrinh
force-pushed
the
quickstart-next
branch
2 times, most recently
from
149c3ab to
c3cea31
Compare
jaclarke
force-pushed
the
gel-docs-directives
branch
from
43ca0e9 to
9719a03
Compare
scotttrinh
force-pushed
the
quickstart-next
branch
from
16704de to
e54e840
Compare
Docs preview deploy✅ Successfully deployed docs preview for commit e5d167e: https://edgedb-docs-17ruec9gk-edgedb.vercel.app (Last updated: Feb 19, 2025, 14:40:44 UTC) |
- Show query builder in the very first example - Move query strings (and query builder expression) out of the route handler function to make the route handler more readable. - Use JS to get an `order` value for the card instead of EdgeQL - Make the tip about parsing input data more emphatic
scotttrinh
force-pushed
the
quickstart-next
branch
from
1feb3b5 to
36edf77
Compare
scotttrinh
force-pushed
the
quickstart-next
branch
from
36edf77 to
9335c11
Compare
scotttrinh
changed the title
It works fine without the namespace, but if any other tool happened to shadow that same name, it would break.
docs/intro/quickstart/modeling.rst
Outdated
|
|
||
| .. edb:split-section:: | ||
|
|
||
| Let's take a look at the schema we've generated in our built-in database UI. We can use this tool to visualize our data model and see the object types and links we've defined. |
There was a problem hiding this comment.
We need like a gallery widget here. First screenshot will be dashboard with circled button for "Schema Viewer", second will be the viewer
| Let's take a look at the schema we've generated in our built-in database UI. We can use this tool to visualize our data model and see the object types and links we've defined. | |
| Let's take a look at the schema we've generated in our built-in database UI. We can use it to visualize our data model and see the object types and links we've defined. |
docs/intro/quickstart/setup.rst
Outdated
|
|
||
| .. edb:split-section:: | ||
|
|
||
| Use git to clone the Next.js starter template into a new directory called ``flashcards``. This will create a fully configured Next.js project and a local |Gel| instance with an empty schema. You will see the database instance being installed and the project being initialized. You are now ready to start building the application. |
There was a problem hiding this comment.
maybe we can add link to github repo anyway
maybe say: instance being created instead of installed even tho we repeat the create
| - ``gel.toml``: The configuration file for the Gel project instance. Notice that we have a ``hooks.migration.apply.after`` hook that will run ``npx @gel/generate edgeql-js`` after migrations are applied. This will generate the query builder code that you'll use to interact with the database. More details on that to come! | ||
| - ``dbschema/``: This directory contains the schema for the database, and later supporting files like migrations, and generated code. | ||
| - ``dbschema/default.gel``: The default schema file that you'll use to define your data model. It is empty for now, but you'll add your data model to this file in the next step. | ||
| - ``lib/gel.ts``: A utility module that exports the Gel client, which you'll use to interact with the database. |
There was a problem hiding this comment.
maybe just say files instead of new files (all files are new), I am biased to think that new files are generated with gel project init, but here actually nothing new is created because it already exist in the cloned folder, ofc I know that new users don't have this bias... I just find it weird to say new files, maybe is just me.
There was a problem hiding this comment.
Yeah, I meant "new to you" as in: "you already recognize most of the files since they're Next.js app router files, here are the ones you do not recognize". I'll reword!
docs/intro/quickstart/modeling.rst
Outdated
|
|
||
| .. edb:split-section:: | ||
|
|
||
| The flashcards application has a simple data model, but it's interesting enough to get a taste of many of the features of the |Gel| schema language. You have a ``Card`` type that describes a single flashcard, which for now contains two required string properties: ``front`` and ``back``. Each ``Card`` belongs to a ``Deck``, and there is an explicit ordering to the cards in a given deck. |
There was a problem hiding this comment.
of many features instead of of many of the features, or we can say sth along the lines: The flashcards application has a straightforward data model, yet it's engaging enough to showcase many features of the Gel schema language.
|
|
||
| .. code-block:: typescript | ||
|
|
||
| interface Card { |
There was a problem hiding this comment.
in the tutorial app we define RawJSONCard and RawJSONDeck in both lib/models and in the app/model, is that needed?
There was a problem hiding this comment.
Yeah, we don't need both, PRs welcome, but that's more of an implementation detail than something related to the quickstart text itself. We don't actually mention those model modules directly.
docs/intro/quickstart/modeling.rst
Outdated
|
|
||
| The flashcards application has a simple data model, but it's interesting enough to get a taste of many of the features of the |Gel| schema language. You have a ``Card`` type that describes a single flashcard, which for now contains two required string properties: ``front`` and ``back``. Each ``Card`` belongs to a ``Deck``, and there is an explicit ordering to the cards in a given deck. | ||
|
|
||
| Looking at the mock data, you can see this structure in the JSON. |
There was a problem hiding this comment.
maybe to mention here that we mean the file deck-edgeql.json?
actually there is also empty file decks.json, s maybe we delete that one and rename the deck-edgeql.json to deck.json?
There was a problem hiding this comment.
decks.json is where the data lives once you import the deck-edgeql.json, so I'd like to keep that rather than make the actions module more complicated by needing to check if it exists, etc.
maybe to mention here that we mean the file deck-edgeql.json?
Yeah, that's a good call. Maybe show a bit of the data itself.
docs/intro/quickstart/modeling.rst
Outdated
|
|
||
| To make |Gel| do that, you need to do two quick steps: | ||
|
|
||
| 1. **Create a migration**: a file with a list of low-level instructions. |
There was a problem hiding this comment.
I'd explain this a bit more clearly:
Create a migration: a file containing a set of low level instructions that define how the database schema should change. It records any additions, modifications, or deletions to your schema in a way that the database can understand.
and something along the lines:
Apply the migration: This executes the migration file, instructing Gel to implement the recorded changes in the database. Essentially, this step updates the database structure to match your defined schema, ensuring that the Deck and Card types are created and ready for use.
docs/intro/quickstart/connecting.rst
Outdated
|
|
||
| .. note:: | ||
|
|
||
| Notice that the ``createClient`` function isn't being passed any connection details. How does |Gel| know how to connect to the database you set up earlier? When we ran ``npx gel project init`` earlier, the CLI created credentials for the local database and stored them in a well-known location. When you initialize your client with ``createClient()``, |Gel| will check the places it knows about for connection details. |
There was a problem hiding this comment.
maybe: the CLI created credentials for the local database and stored them in a well-known location on disk. When you initialize your client with createClient(), Gel will check these known locations on your machine for connection details."
There was a problem hiding this comment.
It checks both this project location and also environment variables, as well as explicit connection details. What I'm trying to say here is that you do not ever need to worry about createClient: locally it will use the project details, and in production, you use environment variables. I'll try to make that more clear.
There was a problem hiding this comment.
yes yes I know it check all those things, if u think what is already here is good enough feel free to ignore my comment : ) I feel like we should try to give a bit more explanations in the tutorial and more links to the reference docs
There was a problem hiding this comment.
Yeah, in general my feelings on the quick start are:
- Do not give more details than absolutely necessary or make the user make any decisions. This is a guided path, not an exploration.
- We absolutely should provide more resources in each section to the relevant documentation for further reading.
To the first point, what "absolutely necessary" means is open to interpretation, and our createClient flow is just unusual enough to require some explanation, but I think it needs to be as absolutely limited as possible without being confusing. Just give enough detail to answer the most obvious questions a typical reader might have.
As far as linking to more details: absolutely! We're currently rewriting all of the documentation, so we don't yet have links to these places. As soon as we do, we should do another pass and add links and resources sections to each one.
Also inline the queries in the actions to avoid needing to talk through why you might want to do that.
Conflicts: docs/intro/quickstart.rst tests/test_docs_sphinx_ext.py
Typically around needing to cast string literals as UUID
No description provided.