wip ensure up to date guides and docs

Author: HomelessDinosaur

docs/get-started/quickstart.mdx

@@ -159,7 +159,7 @@ Your project should now look like this:
 
 ```txt TypeScript
 +--services/
-|  +-- hello.ts
+|  +-- api.ts
 +--node_modules/
 |  ...
 +--package-lock.json
@@ -174,7 +174,7 @@ Your project should now look like this:
 
 ```txt JavaScript
 +--services/
-|  +-- hello.js
+|  +-- api.js
 +--node_modules/
 |  ...
 +--package-lock.json
@@ -220,7 +220,7 @@ Your project should now look like this:
 
 ```txt Dart
 +--services/
-|  +-- hello.dart
+|  +-- api.dart
 +--analysis_options.yaml
 +--pubspec.lock
 +--pubspec.yaml
@@ -270,7 +270,7 @@ Start by opening the `hello` service in your editor and adding a new route to th
 
 <CodeSwitcher tabs>
 
-```typescript !! title:services/hello.ts
+```typescript title:services/api.ts
 import { api } from '@nitric/sdk'
 
 const helloApi = api('main')
@@ -289,7 +289,7 @@ helloApi.get('/goodbye/:name', async (ctx) => {
 })
 ```
 
-```javascript !! title:services/hello.js
+```javascript title:services/api.js
 import { api } from '@nitric/sdk'
 
 const helloApi = api('main')
@@ -308,7 +308,7 @@ helloApi.get('/goodbye/:name', async (ctx) => {
 })
 ```
 
-```python !! title:services/hello.py
+```python title:services/api.py
 from nitric.resources import api
 from nitric.application import Nitric
 
@@ -357,7 +357,7 @@ func main() {
 }
 ```
 
-```dart !! title:services/hello.dart
+```dart title:services/api.dart
 import 'package:nitric_sdk/nitric.dart';
 
 void main() {

docs/guides/nodejs/expressjs.mdx

@@ -7,7 +7,7 @@ languages:
   - typescript
   - javascript
 published_at: 2023-07-10
-updated_at: 2024-03-18
+updated_at: 2024-12-27
 ---
 
 # Enhance Express.js Apps with Cloud Resources
@@ -42,7 +42,7 @@ You can go ahead and open this new project in your editor of choice. You should
 
 ```txt
 ├── services
-│   ├── hello.js
+│   ├── api.js
 ├── node_modules
 │   ├── ...
 ├── .gitignore
@@ -55,17 +55,9 @@ You can go ahead and open this new project in your editor of choice. You should
 
 In this structure you'll notice the `services` folder. By default, this is where Nitric expects the entrypoint code for your application. However, that's just a convention, we can change that to anything else that suits our needs.
 
-Let's start by replacing the default `hello.js` service with an `app.js` file ready for the Express.js application:
-
-```bash
-rm ./services/hello.js
-
-touch ./services/app.js
-```
-
 Now, let's add some express code to get things started.
 
-```javascript {{ label: 'services/app.js' }}
+```javascript title:services/api.js
 import express from 'express'
 import { http } from '@nitric/sdk'
 const app = express()
@@ -100,9 +92,9 @@ Hello World!
 
 With everything working so far, now is a good time to see how we can add new resources to the Express app using Nitric. In this example, let's add a pub/sub topic which allows us to perform work in the background, but still respond quickly via the HTTP API.
 
-You can update the `app.js` file like so:
+You can update the `api.js` file like so:
 
-```javascript {{ label: 'services/app.js' }}
+```javascript title:services/api.js
 import express from 'express'
 import { http, topic } from '@nitric/sdk'
 
@@ -125,7 +117,7 @@ touch services/worker.js
 
 Add this code to that file:
 
-```javascript {{ label: 'services/worker.js' }}
+```javascript title:services/worker.js
 import { topic } from '@nitric/sdk'
 
 const sleep = (ms) => new Promise((res) => setTimeout(res, ms))
@@ -166,7 +158,7 @@ nitric stack new
 
 This command will create a file named `nitric.dev.yaml`, with contents like this:
 
-```yaml {{ label: 'nitric.dev.yaml' }}
+```yaml title:nitric.dev.yaml
 provider: nitric/[email protected]
 region: us-east-1
 ```

docs/guides/nodejs/fastify.mdx

@@ -7,7 +7,7 @@ languages:
   - typescript
   - javascript
 published_at: 2023-07-12
-updated_at: 2024-03-18
+updated_at: 2024-12-27
 ---
 
 # Add Cloud Resources to Fastify Apps
@@ -42,7 +42,7 @@ You can go ahead and open this new project in your editor of choice. You should
 
 ```txt
 ├── services
-│   ├── hello.js
+│   ├── api.js
 ├── node_modules
 │   ├── ...
 ├── .gitignore
@@ -54,18 +54,9 @@ You can go ahead and open this new project in your editor of choice. You should
 ```
 
 In this structure you'll notice the `servuces` folder. By default, this is where Nitric expects the entrypoint code for your application. However, that's just a convention, we can change that to anything else that suits our needs.
-
-Let's start by replacing the default `hello.js` service with an `app.js` file ready for the Fastify application:
-
-```bash
-rm ./services/hello.js
-
-touch ./services/app.js
-```
-
 Now, let's add some Fastify code to get things started.
 
-```javascript {{ label: 'services/app.js' }}
+```javascript title:services/app.js
 import Fastify from 'fastify'
 import { http } from '@nitric/sdk'
 
@@ -94,7 +85,7 @@ nitric start
 
 Your Fastify application will now be running with Nitric acting as a proxy. We can test this in another terminal or web browser.
 
-```bash {{ label: 'terminal' }}
+```bash
 curl http://localhost:4001
 Hello World!
 ```
@@ -105,7 +96,7 @@ With everything working so far, now is a good time to see how we can add new res
 
 You can update the `app.js` file like so:
 
-```javascript {{ label: 'services/app.js' }}
+```javascript title:services/app.js
 import Fastify from 'fastify'
 import { http, topic } from '@nitric/sdk'
 
@@ -138,7 +129,7 @@ touch services/worker.js
 
 Add this code to that file:
 
-```javascript {{ label: 'services/worker.js' }}
+```javascript title:services/worker.js
 import { topic } from '@nitric/sdk'
 
 const sleep = (ms) => new Promise((res) => setTimeout(res, ms))
@@ -173,13 +164,13 @@ To perform the deployment we'll create a `stack`, stacks give Nitric the config
 
 The new stack command can help you create the stack by following prompts.
 
-```bash {{ label: 'terminal' }}
+```bash
 nitric stack new
 ```
 
 This command will create a file named `nitric.dev.yaml`, with contents like this:
 
-```yaml {{ label: 'nitric.dev.yaml' }}
+```yaml title:nitric.dev.yaml
 provider: nitric/[email protected]
 region: us-east-1
 ```

docs/guides/nodejs/graphql.mdx

@@ -7,7 +7,7 @@ languages:
   - typescript
   - javascript
 published_at: 2022-11-17
-updated_at: 2024-03-18
+updated_at: 2024-12-27
 ---
 
 # Building a GraphQL API with Nitric
@@ -56,7 +56,7 @@ The scaffolded project should have the following structure:
 
 ```text
 +--services/
-|  +-- hello.ts
+|  +-- api.ts
 +--node_modules/
 |  ...
 +--nitric.yaml
@@ -67,17 +67,9 @@ The scaffolded project should have the following structure:
 You can test the project to verify everything is working as expected:
 
 ```bash
-npm run dev
+nitric start
 ```
 
-<Note>
-  The `dev` script starts the Nitric Server using `nitric start`, which provides
-  local interfaces to emulate cloud resources, then runs your services and
-  allows them to connect.
-</Note>
-
-If everything is working as expected you can now delete all files in the `services/` folder, we'll create new services in this guide.
-
 ## Build the GraphQL Schema
 
 GraphQL requests are typesafe, and so they require a schema to be defined to validate queries.
@@ -89,10 +81,9 @@ npm install graphql
 npm install uuid
 ```
 
-Create a new file named 'graphql.ts' in the services folder.
 We can then import `buildSchema`, and write out the schema.
 
-```typescript
+```typescript title:services/api.ts
 import { graphql, buildSchema } from 'graphql'
 import { v4 as uuid } from 'uuid'
 
@@ -123,7 +114,7 @@ const schema = buildSchema(`
 
 We will also define a few types to mirror the schema definition.
 
-```typescript
+```typescript title:services/api.ts
 interface Profile {
   pid: string
   name: string
@@ -138,7 +129,7 @@ type ProfileInput = Omit<Profile, 'pid'>
 
 Lets define a KV resource for the resolvers get/set data from with some helper functions for serialization.
 
-```typescript
+```typescript title:services/api.ts
 import { kv } from '@nitric/sdk'
 
 const profiles = kv('profiles').allow('get', 'set')
@@ -171,7 +162,7 @@ async function updateProfiles(profileList) {
 
 We can create a resolver object for use by the graphql handler.
 
-```typescript
+```typescript title:services/api.ts
 const resolvers = {
   createProfile,
   fetchProfiles,
@@ -185,7 +176,7 @@ We can then use the KV resource within these services. Each resolver will receiv
 
 ## Create a profile
 
-```typescript
+```typescript title:services/api.ts
 const createProfile = async ({ profile }): Promise<Profile> => {
   const profileList = await getProfiles()
   profile.pid = uuid()
@@ -197,15 +188,15 @@ const createProfile = async ({ profile }): Promise<Profile> => {
 
 ## Get all profiles
 
-```typescript
+```typescript title:services/api.ts
 const fetchProfiles = async (): Promise<Profile[]> => {
   return await getProfiles()
 }
 ```
 
 ## Get a profile by its ID
 
-```typescript
+```typescript title:services/api.ts
 const fetchProfile = async ({ pid }): Promise<Profile> => {
   const profileList = await getProfiles()
   const profile = profileList.find((profile) => profile.pid === pid)
@@ -219,15 +210,15 @@ We'll define an api to put our handler in. This api will only have one endpoint,
 
 Update the imports to include api and declare the api.
 
-```typescript
+```typescript title:services/api.ts
 import { api, kv } from '@nitric/sdk'
 
 const profileApi = api('public')
 ```
 
 Then add the api handler.
 
-```typescript
+```typescript title:services/api.ts
 import { graphql, buildSchema } from 'graphql'
 
 profileApi.post('/', async (ctx) => {
@@ -249,18 +240,11 @@ Now that you have an API defined with a handler for the GraphQL requests, it's t
 Test out your application with the following command:
 
 ```bash
-npm run dev
+nitric start
 ```
 
-<Note>
-  The `dev` script in the template starts the Nitric Server using `nitric start`
-  and runs your services.
-</Note>
-
 Once it starts, the application will be able to receive requests via the API port.
 
-Pressing `ctrl + a + k` will end the application.
-
 ## GraphQL Queries
 
 We can use cURL, postman or any other HTTP Client to test our application, however it's better if the client has GraphQL support.
@@ -370,31 +354,34 @@ curl --location -X POST \
 
 ## Deploy to the cloud
 
-Setup your credentials and any other cloud specific configuration:
+At this point, you can deploy what you've built to any of the supported cloud providers. In this example we'll deploy to AWS. Start by setting up your credentials and configuration for the [nitric/aws provider](/providers/pulumi/aws).
 
-- [AWS](/providers/pulumi/aws)
-- [Azure](/providers/pulumi/azure)
-- [GCP](/providers/pulumi/gcp)
+Next, we'll need to create a `stack file` (deployment target). A stack is a deployed instance of an application. You might want separate stacks for each environment, such as stacks for `dev`, `test`, and `prod`. For now, let's start by creating a file for the `dev` stack.
 
-Create a stack - a collection of resources identified in your project which will be deployed.
+The `stack new` command below will create a stack named `dev` that uses the `aws` provider.
 
 ```bash
-nitric stack new
+nitric stack new dev aws
 ```
 
-```
-? What should we name this stack? dev
-? Which provider do you want to deploy with? aws
-? Which region should the stack deploy to? us-east-1
-```
+Edit the stack file `nitric.dev.yaml` and set your preferred AWS region, for example `us-east-1`.
 
-You can then deploy using the following command:
+### AWS
+
+<Note>
+  You are responsible for staying within the limits of the free tier or any
+  costs associated with deployment.
+</Note>
+
+Let's try deploying the stack with the `up` command:
 
 ```bash
 nitric up
 ```
 
-To undeploy run the following command:
+When the deployment is complete, go to the relevant cloud console and you'll be able to see and interact with your WebSocket application.
+
+To tear down your application from the cloud, use the `down` command:
 
 ```bash
 nitric down