diff --git a/content/guides/civet-guest-book.md b/content/guides/civet-guest-book.md index 6b61baaa42..55babca12c 100644 --- a/content/guides/civet-guest-book.md +++ b/content/guides/civet-guest-book.md @@ -1,6 +1,6 @@ --- title: Building a guest book with Civet -subtitle: Building a guest book with Civet in its very early state +subtitle: Building a guest book with Civet and exploring the pros and cons of the language author: astrid-gealer enableTableOfContents: true createdAt: '2024-10-24T00:00:00.000Z' @@ -21,25 +21,25 @@ A language alone isn't too helpful if it cannot integrate into your existing cod To get started, I simply ran `npx create-next-app` with all of the default options. From here, I ran `npm i -D @danielx/civet` to install the civet compiler and then added it to the webpack options in `next.config.ts` (whilst changing their template to be compatible). From here, I noticed that it isn't typed so you cannot use the new Next TS configuration with it: -![VS Code showing invalid types](civet_notes/bad_types.png) +![VS Code showing invalid types](/docs/guides/civet/bad_types.png) This is a unfortunate sign for something that claims to be "99% JS/TS compatible". However, after rolling back to [their JS config that uses the legacy Next way with RequireJS](https://github.com/DanielXMoore/Civet/blob/a365833803e193f46b8552692e0955cc09bfd76c/integration/unplugin-examples/nextjs/next.config.js), I did see no errors and was able to start the development server! Lets make a simple guest book using server components and Drizzle for the database. The first thing I did was remove `page.tsx` and `layout.tsx` and create a `page.civet` file with a simple hello world page just to make sure everything was working as expected. The first thing you will notice is that VS Code does not have native support, so you need to download the Civet language server from the extensions marketplace. This enables the icon for Civet and syntax highlighting, which you can see when you hover is using the TypeScript server under the hood. The first thing I initially noticed was that copilot was autocompleting JavaScript in these files: -![copilot autocompletes JS](civet_notes/copilot.png) +![copilot autocompletes JS](/docs/guides/civet/copilot.png) This is a flaw that all new languages are going to face that are not syntactically similar to others in the AI world unfortunately, and it is going to require new training data to be able to fix this. Unfortunately, this does hurt some of the productivity claims if you are a heavy user of AI solutions to get your work done. As I was just getting started, I wrote this code by accident which is invalid syntax: -![invalid civet syntax](civet_notes/civet_error.png) +![invalid civet syntax](/docs/guides/civet/civet_error.png) This resulted in the following in the console: -![civet console error](civet_notes/civet_console.png) +![civet console error](/docs/guides/civet/civet_console.png) With no output to the browser. This is important to remember when developing that the tooling is nowhere near as mature as for TS/JS yet, and errors within Civet seem to crash the entire next runtime. After realising my error that the problem was related to the fact that functions still had to be marked as such outside of classes, the code looked like this: -![civet correct syntax](civet_notes/civet_ok.png) +![civet correct syntax](/docs/guides/civet/civet_ok.png) Which is quite clean in my opinion! The lack of a closing tag is intentional since Civet does not require one if it is single line or there is indentation. Additionally, the return keyword is not needed because Civet has Rust-like behaviour of implicit returns. Whether you like this or not will come down to personal preference. @@ -47,15 +47,15 @@ Sure enough, I went to my browser and saw hello world waiting for me. The first The first thing I noticed whilst doing this was that importing the global CSS file caused the server to crash, when I rebooted, I was faced with a weird build error: -![Next no such directory error](civet_notes/no_such_directory.png) +![Next no such directory error](/docs/guides/civet/no_such_directory.png) This persisted across development server reboots, only resolving itself when I removed the `.next` directory and restarted the development server. The layout would've been equally impressive, but unfortunately I was getting issues importing the CSS with this: -![layout](civet_notes/layout.png) +![layout](/docs/guides/civet/layout.png) After I did this, I played around with some of the TSX shortcuts within Civet. The first thing I tried was the class name shortener within Civet's implementation of TSX. I did notice that by default, it tried to apply this to the `class` attribute which is disallowed in React, but luckily Civet has some other configuration options that we can use: -![adding text-lg on Civet](civet_notes/civet_class.png) +![adding text-lg on Civet](/docs/guides/civet/civet_class.png) After adding this, we successfully got the styles applied to the component! This in my opinion is really nice syntax and will make simple class adjustments a lot less clumbersome than they are in regular TSX, especially to new engineers. It is important to note, though, that Tailwind support is not yet implemented yet so although the compiler works, code suggestions do not. @@ -92,27 +92,27 @@ export default defineConfig({ Next, we can add the scripts required for database migrations to our `package.json`: ```json - "db:generate-migrations": "drizzle-kit generate", - "db:migrate": "drizzle-kit migrate" +"db:generate-migrations": "drizzle-kit generate", +"db:migrate": "drizzle-kit migrate" ``` And we can run `npm run db:generate-migrations` and `npm run db:migrate` (with `DATABASE_URL` set) to migrate our Neon database. With the database migrated, lets integrate this into our project. We will create the file `singletons/database.civet` to do our database connection. One thing I noticed doing this was the performance of the TS server felt quite slow: -![TS server being slow](civet_notes/slowness.png) +![TS server being slow](/docs/guides/civet/slowness.png) With all that said, when it was done, the file was very clean: -![contents of singletons/database.civet](civet_notes/clean_db_file.png) +![contents of singletons/database.civet](/docs/guides/civet/clean_db_file.png) Ok, great! Lets now integrate this into our application. The first thing I did was add `m-20` to the layout file, and then I started adding the functionality to the page using server components. Off the bat, the first thing I did notice was that the highlighting was a bit buggy. It mostly worked great, but there were problems, especially with TSX: -![syntax highlighting bug](civet_notes/syntax_highlighting.png) +![syntax highlighting bug](/docs/guides/civet/syntax_highlighting.png) Another thing I noticed was that import aliases seemed to break with Civet: -![import path alias error](civet_notes/path_alias_error.png) +![import path alias error](/docs/guides/civet/path_alias_error.png) I in fact had such a big problem getting this to work that I had to migrate the singleton to TypesScript: @@ -130,7 +130,7 @@ export default drizzle(pool, { schema }); After I wrote all the code (whilst battling lots of crashes), the code was very clean and made very good use of indentation in my opinion: -![guest book code](civet_notes/guest_book_code.png) +![guest book code](/docs/guides/civet/guest_book_code.png) With this, we have a fully working guest book! There are a few things I noticed though: diff --git a/public/docs/guides/civet/bad_types.png b/public/docs/guides/civet/bad_types.png new file mode 100644 index 0000000000..225fa496e4 Binary files /dev/null and b/public/docs/guides/civet/bad_types.png differ diff --git a/public/docs/guides/civet/civet_class.png b/public/docs/guides/civet/civet_class.png new file mode 100644 index 0000000000..3800f17b1f Binary files /dev/null and b/public/docs/guides/civet/civet_class.png differ diff --git a/public/docs/guides/civet/civet_console.png b/public/docs/guides/civet/civet_console.png new file mode 100644 index 0000000000..eabc44a1c0 Binary files /dev/null and b/public/docs/guides/civet/civet_console.png differ diff --git a/public/docs/guides/civet/civet_error.png b/public/docs/guides/civet/civet_error.png new file mode 100644 index 0000000000..b4b5571c65 Binary files /dev/null and b/public/docs/guides/civet/civet_error.png differ diff --git a/public/docs/guides/civet/civet_ok.png b/public/docs/guides/civet/civet_ok.png new file mode 100644 index 0000000000..976021b01a Binary files /dev/null and b/public/docs/guides/civet/civet_ok.png differ diff --git a/public/docs/guides/civet/clean_db_file.png b/public/docs/guides/civet/clean_db_file.png new file mode 100644 index 0000000000..2d130ccf8d Binary files /dev/null and b/public/docs/guides/civet/clean_db_file.png differ diff --git a/public/docs/guides/civet/copilot.png b/public/docs/guides/civet/copilot.png new file mode 100644 index 0000000000..6f709726b8 Binary files /dev/null and b/public/docs/guides/civet/copilot.png differ diff --git a/public/docs/guides/civet/guest_book_code.png b/public/docs/guides/civet/guest_book_code.png new file mode 100644 index 0000000000..f1c83bb98b Binary files /dev/null and b/public/docs/guides/civet/guest_book_code.png differ diff --git a/public/docs/guides/civet/hello_world.png b/public/docs/guides/civet/hello_world.png new file mode 100644 index 0000000000..c80d0b2095 Binary files /dev/null and b/public/docs/guides/civet/hello_world.png differ diff --git a/public/docs/guides/civet/layout.png b/public/docs/guides/civet/layout.png new file mode 100644 index 0000000000..165605ab83 Binary files /dev/null and b/public/docs/guides/civet/layout.png differ diff --git a/public/docs/guides/civet/no_such_directory.png b/public/docs/guides/civet/no_such_directory.png new file mode 100644 index 0000000000..424f2af92f Binary files /dev/null and b/public/docs/guides/civet/no_such_directory.png differ diff --git a/public/docs/guides/civet/path_alias_error.png b/public/docs/guides/civet/path_alias_error.png new file mode 100644 index 0000000000..29a2710f09 Binary files /dev/null and b/public/docs/guides/civet/path_alias_error.png differ diff --git a/public/docs/guides/civet/slowness.png b/public/docs/guides/civet/slowness.png new file mode 100644 index 0000000000..726b5e908e Binary files /dev/null and b/public/docs/guides/civet/slowness.png differ diff --git a/public/docs/guides/civet/syntax_highlighting.png b/public/docs/guides/civet/syntax_highlighting.png new file mode 100644 index 0000000000..5909d31fab Binary files /dev/null and b/public/docs/guides/civet/syntax_highlighting.png differ diff --git a/public/guides/authors/astrid-gealer.jpg b/public/guides/authors/astrid-gealer.jpg new file mode 100644 index 0000000000..6fed43ffbe Binary files /dev/null and b/public/guides/authors/astrid-gealer.jpg differ