diff --git a/.github/workflows/autofix-docs.yml b/.github/workflows/autofix-docs.yml new file mode 100644 index 0000000000..7c6840bcb6 --- /dev/null +++ b/.github/workflows/autofix-docs.yml @@ -0,0 +1,30 @@ +name: autofix.ci # needed to securely identify the workflow + +on: + pull_request: + paths: + - "docs/**" + - ".github/workflows/docs.yml" + +permissions: + contents: read + +jobs: + docs: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + - run: corepack enable + - uses: actions/setup-node@v3 + with: + node-version: 18 + cache: "pnpm" + + - name: Install dependencies + run: pnpm install + + - name: Lint (docs) + run: pnpm lint:docs:fix + + - uses: autofix-ci/action@8bc06253bec489732e5f9c52884c7cace15c0160 diff --git a/.github/workflows/autofix.yml b/.github/workflows/autofix.yml new file mode 100644 index 0000000000..3c47e98c69 --- /dev/null +++ b/.github/workflows/autofix.yml @@ -0,0 +1,42 @@ +name: autofix.ci # needed to securely identify the workflow + +on: + pull_request: + paths-ignore: + - "docs/**" + +permissions: + contents: read + +jobs: + code: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + - run: corepack enable + - uses: actions/setup-node@v3 + with: + node-version: 18 + cache: "pnpm" + + - name: Install dependencies + run: pnpm install + + - name: Dedupe dependencies + if: ${{ contains(github.ref_name, 'renovate') }} + run: pnpm dedupe + + - name: Build (stub) + run: pnpm build:stub + + - name: Lint (code) + run: pnpm lint:fix + + - name: Test (unit) + run: pnpm test:unit -u + + - name: Update bundle size + run: pnpm vitest run bundle -u + + - uses: autofix-ci/action@8bc06253bec489732e5f9c52884c7cace15c0160 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0dd3c6fcd6..bc7bb96e26 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -88,6 +88,8 @@ jobs: run: pnpm test:types lint: + # autofix workflow will be triggered instead for PRs + if: github.event_name == 'push' runs-on: ubuntu-latest timeout-minutes: 10 @@ -169,9 +171,6 @@ jobs: - name: Test (unit) run: pnpm test:unit - env: - TEST_ENV: ${{ matrix.env }} - TEST_BUILDER: ${{ matrix.builder }} - name: Test (fixtures) run: pnpm test:fixtures diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index d9213610e7..a2d96f9a06 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -5,30 +5,24 @@ on: paths: - "docs/**" - ".github/workflows/docs.yml" + # autofix workflow will be triggered instead for PRs branches: - main - pull_request: - paths: - - "docs/**" - - ".github/workflows/docs.yml" - branches: - - main + +# Remove default permissions of GITHUB_TOKEN for security +# https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs +permissions: {} jobs: lint-docs: - runs-on: ${{ matrix.os }} - - strategy: - matrix: - os: [ubuntu-latest] - node: [14] + runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - run: corepack enable - uses: actions/setup-node@v3 with: - node-version: ${{ matrix.node }} + node-version: 18 cache: "pnpm" - name: Install dependencies diff --git a/.github/workflows/introspect.yml b/.github/workflows/introspect.yml index 4e295577e6..99b843dc71 100644 --- a/.github/workflows/introspect.yml +++ b/.github/workflows/introspect.yml @@ -1,4 +1,4 @@ -name: Docs +name: CI on: push: diff --git a/.markdownlint.yml b/.markdownlint.yml index 15a0e34464..c1fac0779d 100644 --- a/.markdownlint.yml +++ b/.markdownlint.yml @@ -12,3 +12,5 @@ MD025: false MD033: false # Allow non blank lines around list MD032: false +MD046: + style: fenced diff --git a/.markdownlintignore b/.markdownlintignore index 04a20c4d4c..76059468f3 100644 --- a/.markdownlintignore +++ b/.markdownlintignore @@ -1,5 +1,5 @@ **/node_modules -docs/content/index.md -docs/content/**/*.nuxt.config.md -docs/content/changelog.md +docs/0.index.md +docs/1.getting-started/1.introduction.md +docs/**/*.nuxt.config.md diff --git a/docs/0.prologue/1.auto-imports.md b/docs/0.prologue/1.auto-imports.md index b08052793d..a7888a3b0b 100644 --- a/docs/0.prologue/1.auto-imports.md +++ b/docs/0.prologue/1.auto-imports.md @@ -17,6 +17,10 @@ You can find a reference for auto-imported [composables](/docs/api/composables/u In the [server directory](/docs/guide/directory-structure/server), we auto import exported functions and variables from `server/utils/`. :: +::alert +You can also auto-import functions exported from custom folders or third-party packages by configuring the [`imports` section](/docs/api/configuration/nuxt-config#imports) of your `nuxt.config` file. +:: + ## Built-in Auto-imports ### Nuxt Auto-imports @@ -46,7 +50,7 @@ Vue 3 exposes Reactivity APIs like `ref` or `computed`, as well as lifecycle hoo -When you are using the built-in composition API composables provided by Vue and Nuxt, be aware that many of them rely on being called in the right _context_. +When you are using the built-in Composition API composables provided by Vue and Nuxt, be aware that many of them rely on being called in the right _context_. During a component lifecycle, Vue tracks the temporary instance of the current component (and similarly, Nuxt tracks a temporary instance of `nuxtApp`) via a global variable, and then unsets it in same tick. This is essential when server rendering, both to avoid cross-request state pollution (leaking a shared reference between two users) and to avoid leakage between different components. diff --git a/docs/1.getting-started/10.deployment.md b/docs/1.getting-started/10.deployment.md index 0627b89591..b816e2b27d 100644 --- a/docs/1.getting-started/10.deployment.md +++ b/docs/1.getting-started/10.deployment.md @@ -141,7 +141,7 @@ Nuxt 3 can be deployed to several cloud providers with a minimal amount of confi - :icon{name="logos:microsoft-azure" class="h-5 w-4 inline mb-2"} [Azure](https://nitro.unjs.io/deploy/providers/azure) - :icon{name="ph:cloud-duotone" class="h-5 w-4 inline mb-2"} [Cleavr](https://nitro.unjs.io/deploy/providers/cleavr) - :icon{name="logos:cloudflare" class="h-5 w-4 inline mb-2"} [CloudFlare](https://nitro.unjs.io/deploy/providers/cloudflare) -- :icon{name="logos:digital-ocean" class="h-5 w-4 inline mb-2"} [Digital Ocean](https://nitro.unjs.io/deploy/providers/digitalocean) +- :icon{name="logos:digital-ocean" class="h-5 w-4 inline mb-2"} [DigitalOcean](https://nitro.unjs.io/deploy/providers/digitalocean) - :icon{name="logos:firebase" class="h-5 w-4 inline mb-2"} [Firebase](https://nitro.unjs.io/deploy/providers/firebase) - :icon{name="logos:heroku-icon" class="h-5 w-4 inline mb-2"} [heroku](https://nitro.unjs.io/deploy/providers/heroku) - :icon{name="ph:cloud-duotone" class="h-5 w-4 inline mb-2"} [Edgio](https://nitro.unjs.io/deploy/providers/edgio) diff --git a/docs/1.getting-started/2.installation.md b/docs/1.getting-started/2.installation.md index c568166951..2db33a6ec4 100644 --- a/docs/1.getting-started/2.installation.md +++ b/docs/1.getting-started/2.installation.md @@ -19,28 +19,32 @@ Start with one of our starters and themes directly by opening [nuxt.new](https:/ ## New Project + + #### Prerequisites + - **Node.js** - [`v16.10.0`](https://nodejs.org/en/) or newer -- **Text editor** - We recommend [Visual Studio Code]() with the [Volar Extension](https://marketplace.visualstudio.com/items?itemName=Vue.volar) +- **Text editor** - We recommend [Visual Studio Code](https://code.visualstudio.com/) with the [Volar Extension](https://marketplace.visualstudio.com/items?itemName=Vue.volar) - **Terminal** - In order to run Nuxt commands ::alert - ::details - :summary[Additional notes for an optimal setup:] - - **Node.js**: Make sure to use an even numbered version (16, 18, etc) +::details +:summary[Additional notes for an optimal setup:] +- **Node.js**: Make sure to use an even numbered version (16, 18, etc) - - **Volar**: Either enable [**Take Over Mode**](https://vuejs.org/guide/typescript/overview.html#volar-takeover-mode) (recommended) or add the [TypeScript Vue Plugin](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) +- **Volar**: Either enable [**Take Over Mode**](https://vuejs.org/guide/typescript/overview.html#volar-takeover-mode) (recommended) or add the [TypeScript Vue Plugin](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) - If you have enabled **Take Over Mode** or installed the **TypeScript Vue Plugin (Volar)**, you can disable generating the shim for `*.vue` files in your `nuxt.config.ts` file: +If you have enabled **Take Over Mode** or installed the **TypeScript Vue Plugin (Volar)**, you can disable generating the shim for `*.vue` files in your `nuxt.config.ts` file: - ```ts [nuxt.config.ts] - export default defineNuxtConfig({ - typescript: { - shim: false - } - }) - ``` - :: +```ts [nuxt.config.ts] +export default defineNuxtConfig({ + typescript: { + shim: false + } +}) +``` + +:: :: Open a terminal (if you're using [Visual Studio Code](https://code.visualstudio.com/), you can open an [integrated terminal](https://code.visualstudio.com/docs/editor/integrated-terminal)) and use the following command to create a new starter project: @@ -110,4 +114,4 @@ Well done! A browser window should automatically open for +definePageMeta({ + middleware: [ + function (to, from) { + // Custom inline middleware + }, + 'auth', + ], +}); + +``` + +You can expect the middleware to be run in the following order: + +1. `analytics.global.ts` +2. `setup.global.ts` +3. Custom inline middleware +4. `auth.ts` + +### Ordering Global Middleware + +By default, global middleware is executed alphabetically based on the filename. + +However, there may be times you want to define a specific order. For example, in the last scenario, `setup.global.ts` may need to run before `analytics.global.ts`. In that case, we recommend prefixing global middleware with 'alphabetical' numbering. + +```text [middleware/ directory] +middleware/ +--| 01.setup.global.ts +--| 02.analytics.global.ts +--| auth.ts +``` + +::alert{type=info icon=💡} +In case you're new to 'alphabetical' numbering, remember that filenames are sorted as strings, not as numeric values. For example, `10.new.global.ts` would come before `2.new.global.ts`. This is why the example prefixes single digit numbers with `0`. +:: + ## When Middleware Runs If your site is server-rendered or generated, middleware for the initial page will be executed both when the page is rendered and then again on the client. This might be needed if your middleware needs a browser environment, such as if you have a generated site, aggressively cache responses, or want to read a value from local storage. diff --git a/docs/2.directory-structure/1.modules.md b/docs/2.directory-structure/1.modules.md index 4699f8f7f5..79cd6a993b 100644 --- a/docs/2.directory-structure/1.modules.md +++ b/docs/2.directory-structure/1.modules.md @@ -15,6 +15,7 @@ The auto-registered files patterns are: You don't need to add those local modules to your [`nuxt.config.ts`](/docs/guide/directory-structure/nuxt.config) separately. ::code-group + ```ts [modules/hello/index.ts] // `nuxt/kit` is a helper subpath import you can use when defining local modules // that means you do not need to add `@nuxt/kit` to your project's dependencies @@ -35,11 +36,13 @@ export default defineNuxtModule({ } }) ``` + ```ts [modules/hello/runtime/api-route.ts] export default defineEventHandler(() => { return { hello: 'world' } } ``` + :: When starting Nuxt, the `hello` module will be registered and the `/api/hello` route will be available. diff --git a/docs/2.directory-structure/1.pages.md b/docs/2.directory-structure/1.pages.md index 0b605d1dd5..b8bc1c73c7 100644 --- a/docs/2.directory-structure/1.pages.md +++ b/docs/2.directory-structure/1.pages.md @@ -340,7 +340,6 @@ Nuxt 3 allows programmatic navigation through the `navigateTo()` utility method. ```vue