From 18cf0ba8650bde79721c0bd2dcfe2f50597b116e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Mon, 11 Oct 2021 14:57:54 +0200 Subject: [PATCH] chore(docs): improvements (#655) Co-authored-by: Sylvain Marroufin Co-authored-by: Pooya Parsa --- .eslintignore | 1 + .github/PULL_REQUEST_TEMPLATE.md | 17 +- README.md | 31 +- docs/.gitignore | 1 - docs/assets/nuxt.css | 26 + docs/components/Logo.vue | 25 - docs/components/app/AppAside.vue | 118 + docs/components/app/AppFooter.vue | 31 + docs/components/app/AppHeader.vue | 62 + docs/components/app/AppLayout.vue | 39 + docs/components/app/AsideHeaderNavigation.vue | 71 + docs/components/app/AsideNavigation.vue | 100 + docs/components/atoms/Alert.vue | 121 + docs/components/atoms/ButtonLink.vue | 46 + docs/components/atoms/Gem.vue | 121 + docs/components/atoms/GitHubButton.vue | 5 + docs/components/atoms/Headline.vue | 5 + docs/components/atoms/Logo.vue | 26 + docs/components/atoms/NuxtContainer.vue | 18 + docs/components/atoms/SectionButton.vue | 84 + docs/components/atoms/Star.vue | 45 + docs/components/atoms/TwitterButton.vue | 5 + docs/components/atoms/icons/IconCAPI.vue | 3 + docs/components/atoms/icons/IconCLI.vue | 13 + docs/components/atoms/icons/IconClose.vue | 5 + docs/components/atoms/icons/IconCode.vue | 3 + docs/components/atoms/icons/IconDevtools.vue | 13 + docs/components/atoms/icons/IconDirectory.vue | 4 + docs/components/atoms/icons/IconFeather.vue | 13 + docs/components/atoms/icons/IconFile.vue | 4 + .../atoms/icons/IconFileSettings.vue | 4 + docs/components/atoms/icons/IconGit.vue | 4 + docs/components/atoms/icons/IconGitHub.vue | 10 + docs/components/atoms/icons/IconHybrid.vue | 13 + docs/components/atoms/icons/IconKit.vue | 12 + docs/components/atoms/icons/IconNpm.vue | 3 + .../components/atoms/icons/IconNuxtBridge.vue | 3 + docs/components/atoms/icons/IconNuxtNitro.vue | 3 + docs/components/atoms/icons/IconRabbit.vue | 13 + docs/components/atoms/icons/IconSuspense.vue | 13 + docs/components/atoms/icons/IconTwitter.vue | 10 + .../components/atoms/icons/IconTypeScript.vue | 3 + docs/components/atoms/icons/IconVite.vue | 3 + docs/components/atoms/icons/IconVue.vue | 3 + docs/components/atoms/icons/IconWebpack.vue | 13 + docs/components/molecules/HeroParallax.vue | 58 + docs/components/molecules/HeroSection.vue | 33 + docs/components/molecules/HomeHero.vue | 73 + docs/components/organisms/HomeFeatures.vue | 36 + .../organisms/SectionContentItem.vue | 70 + docs/components/templates/Blank.vue | 16 + docs/components/templates/Error.vue | 33 + docs/content/0.index.md | 6 - docs/content/1.get-started/1.installation.md | 49 - docs/content/1.get-started/2.structure.md | 52 - .../1.getting-started/1.introduction.md | 59 + .../1.getting-started/2.installation.md | 43 + docs/content/1.getting-started/3.bridge.md | 78 + docs/content/1.getting-started/4.commands.md | 44 + docs/content/1.getting-started/5.migration.md | 106 + docs/content/1.getting-started/index.md | 7 + docs/content/2.app/1.app.md | 15 - docs/content/2.app/3.data-fetching.md | 33 - docs/content/2.concepts/1.introduction.md | 2 + docs/content/2.concepts/2.server-engine.md | 55 + docs/content/2.concepts/index.md | 7 + .../content/3.docs/1.usage/4.data-fetching.md | 70 + .../{2.app => 3.docs/1.usage}/4.meta-tags.md | 0 docs/content/3.docs/1.usage/index.md | 7 + .../3.docs/2.directory-structure/1.nuxt.md | 16 + .../2.directory-structure/10.plugins.md} | 8 +- .../3.docs/2.directory-structure/11.public.md | 9 + .../3.docs/2.directory-structure/12.server.md | 74 + .../2.directory-structure/13.gitignore.md | 23 + .../3.docs/2.directory-structure/14.app.md | 41 + .../2.directory-structure/15.nuxt.config.md | 508 +++ .../2.directory-structure/16.package.md | 9 + .../3.docs/2.directory-structure/2.output.md | 15 + .../3.docs/2.directory-structure/3.assets.md | 16 + .../2.directory-structure/4.components.md | 9 + .../2.directory-structure/5.composables.md | 9 + .../2.directory-structure/6.layouts.md} | 34 +- .../2.directory-structure/7.node_modules.md | 7 + .../2.directory-structure/8.modules.md} | 12 + .../3.docs/2.directory-structure/9.pages.md | 33 + .../3.docs/2.directory-structure/index.md | 7 + .../5.deployment}/azure-functions.md | 0 .../5.deployment}/azure.md | 0 .../5.deployment}/cloudflare.md | 0 .../5.deployment}/firebase.md | 0 docs/content/3.docs/5.deployment/index.md | 9 + .../5.deployment}/netlify.md | 2 +- .../platforms => 3.docs/5.deployment}/pm2.md | 0 .../5.deployment}/vercel.md | 0 .../5.deployment/zz.presets.md} | 6 +- .../5.deployment/zz.presets/custom.md} | 0 .../5.deployment/zz.presets}/lambda.md | 0 .../5.deployment/zz.presets}/node.md | 0 .../3.docs/5.deployment/zz.presets/server.md | 63 + .../zz.presets}/service-worker.md | 0 docs/content/3.docs/index.md | 6 + docs/content/3.server/1.intro.md | 39 - docs/content/3.server/2.api.md | 43 - docs/content/3.server/3.middleware.md | 23 - .../1.getting-help.md | 0 .../2.reporting-bugs.md | 0 .../3.contribution.md | 0 docs/content/4.community/index.md | 8 + docs/content/4.modules/1.intro.md | 8 - docs/content/6.deployment/1.platforms.md | 13 - docs/content/6.deployment/presets/server.md | 20 - docs/content/7.bridge/1.intro.md | 82 - docs/content/7.bridge/2.migration.md | 136 - docs/content/8.internals/1.how.md | 1 - docs/content/8.internals/2.code.md | 1 - docs/content/8.internals/3.contrib.md | 1 - docs/content/_collections/header.md | 15 + docs/content/index.md | 185 ++ docs/docus.config.ts | 59 +- docs/nuxt.config.ts | 72 +- docs/package.json | 12 +- docs/plugins/mq.js | 14 + docs/scripts/gen-docs.ts | 51 +- docs/static/3D/gem.gltf | 233 ++ docs/static/3D/roughness.jpeg | Bin 0 -> 580100 bytes docs/static/icon.png | Bin 9896 -> 1743 bytes docs/static/img/home/hero/gem-1.svg | 37 + docs/static/img/home/hero/gem-2.svg | 37 + docs/static/img/home/hero/gem-3.svg | 27 + docs/static/img/home/hero/gem-4.svg | 57 + docs/static/img/home/hero/gem-5.svg | 54 + docs/static/img/home/hero/gem-6.svg | 51 + docs/windi.config.js | 138 + docs/yarn.lock | 2904 +++++++++-------- 134 files changed, 5291 insertions(+), 2064 deletions(-) create mode 100644 docs/assets/nuxt.css delete mode 100644 docs/components/Logo.vue create mode 100644 docs/components/app/AppAside.vue create mode 100644 docs/components/app/AppFooter.vue create mode 100644 docs/components/app/AppHeader.vue create mode 100644 docs/components/app/AppLayout.vue create mode 100644 docs/components/app/AsideHeaderNavigation.vue create mode 100644 docs/components/app/AsideNavigation.vue create mode 100644 docs/components/atoms/Alert.vue create mode 100644 docs/components/atoms/ButtonLink.vue create mode 100644 docs/components/atoms/Gem.vue create mode 100644 docs/components/atoms/GitHubButton.vue create mode 100644 docs/components/atoms/Headline.vue create mode 100644 docs/components/atoms/Logo.vue create mode 100644 docs/components/atoms/NuxtContainer.vue create mode 100644 docs/components/atoms/SectionButton.vue create mode 100644 docs/components/atoms/Star.vue create mode 100644 docs/components/atoms/TwitterButton.vue create mode 100644 docs/components/atoms/icons/IconCAPI.vue create mode 100644 docs/components/atoms/icons/IconCLI.vue create mode 100644 docs/components/atoms/icons/IconClose.vue create mode 100644 docs/components/atoms/icons/IconCode.vue create mode 100644 docs/components/atoms/icons/IconDevtools.vue create mode 100644 docs/components/atoms/icons/IconDirectory.vue create mode 100644 docs/components/atoms/icons/IconFeather.vue create mode 100644 docs/components/atoms/icons/IconFile.vue create mode 100644 docs/components/atoms/icons/IconFileSettings.vue create mode 100644 docs/components/atoms/icons/IconGit.vue create mode 100644 docs/components/atoms/icons/IconGitHub.vue create mode 100644 docs/components/atoms/icons/IconHybrid.vue create mode 100644 docs/components/atoms/icons/IconKit.vue create mode 100644 docs/components/atoms/icons/IconNpm.vue create mode 100644 docs/components/atoms/icons/IconNuxtBridge.vue create mode 100644 docs/components/atoms/icons/IconNuxtNitro.vue create mode 100644 docs/components/atoms/icons/IconRabbit.vue create mode 100644 docs/components/atoms/icons/IconSuspense.vue create mode 100644 docs/components/atoms/icons/IconTwitter.vue create mode 100644 docs/components/atoms/icons/IconTypeScript.vue create mode 100644 docs/components/atoms/icons/IconVite.vue create mode 100644 docs/components/atoms/icons/IconVue.vue create mode 100644 docs/components/atoms/icons/IconWebpack.vue create mode 100644 docs/components/molecules/HeroParallax.vue create mode 100644 docs/components/molecules/HeroSection.vue create mode 100644 docs/components/molecules/HomeHero.vue create mode 100644 docs/components/organisms/HomeFeatures.vue create mode 100644 docs/components/organisms/SectionContentItem.vue create mode 100644 docs/components/templates/Blank.vue create mode 100644 docs/components/templates/Error.vue delete mode 100644 docs/content/0.index.md delete mode 100644 docs/content/1.get-started/1.installation.md delete mode 100644 docs/content/1.get-started/2.structure.md create mode 100644 docs/content/1.getting-started/1.introduction.md create mode 100644 docs/content/1.getting-started/2.installation.md create mode 100644 docs/content/1.getting-started/3.bridge.md create mode 100644 docs/content/1.getting-started/4.commands.md create mode 100644 docs/content/1.getting-started/5.migration.md create mode 100644 docs/content/1.getting-started/index.md delete mode 100644 docs/content/2.app/1.app.md delete mode 100644 docs/content/2.app/3.data-fetching.md create mode 100644 docs/content/2.concepts/1.introduction.md create mode 100644 docs/content/2.concepts/2.server-engine.md create mode 100644 docs/content/2.concepts/index.md create mode 100644 docs/content/3.docs/1.usage/4.data-fetching.md rename docs/content/{2.app => 3.docs/1.usage}/4.meta-tags.md (100%) create mode 100644 docs/content/3.docs/1.usage/index.md create mode 100644 docs/content/3.docs/2.directory-structure/1.nuxt.md rename docs/content/{2.app/5.plugins.md => 3.docs/2.directory-structure/10.plugins.md} (65%) create mode 100644 docs/content/3.docs/2.directory-structure/11.public.md create mode 100644 docs/content/3.docs/2.directory-structure/12.server.md create mode 100644 docs/content/3.docs/2.directory-structure/13.gitignore.md create mode 100644 docs/content/3.docs/2.directory-structure/14.app.md create mode 100644 docs/content/3.docs/2.directory-structure/15.nuxt.config.md create mode 100644 docs/content/3.docs/2.directory-structure/16.package.md create mode 100644 docs/content/3.docs/2.directory-structure/2.output.md create mode 100644 docs/content/3.docs/2.directory-structure/3.assets.md create mode 100644 docs/content/3.docs/2.directory-structure/4.components.md create mode 100644 docs/content/3.docs/2.directory-structure/5.composables.md rename docs/content/{2.app/2.pages.md => 3.docs/2.directory-structure/6.layouts.md} (65%) create mode 100644 docs/content/3.docs/2.directory-structure/7.node_modules.md rename docs/content/{4.modules/2.kit.md => 3.docs/2.directory-structure/8.modules.md} (92%) create mode 100644 docs/content/3.docs/2.directory-structure/9.pages.md create mode 100644 docs/content/3.docs/2.directory-structure/index.md rename docs/content/{6.deployment/platforms => 3.docs/5.deployment}/azure-functions.md (100%) rename docs/content/{6.deployment/platforms => 3.docs/5.deployment}/azure.md (100%) rename docs/content/{6.deployment/platforms => 3.docs/5.deployment}/cloudflare.md (100%) rename docs/content/{6.deployment/platforms => 3.docs/5.deployment}/firebase.md (100%) create mode 100644 docs/content/3.docs/5.deployment/index.md rename docs/content/{6.deployment/platforms => 3.docs/5.deployment}/netlify.md (91%) rename docs/content/{6.deployment/platforms => 3.docs/5.deployment}/pm2.md (100%) rename docs/content/{6.deployment/platforms => 3.docs/5.deployment}/vercel.md (100%) rename docs/content/{6.deployment/2.presets.md => 3.docs/5.deployment/zz.presets.md} (81%) rename docs/content/{6.deployment/presets/99.custom.md => 3.docs/5.deployment/zz.presets/custom.md} (100%) rename docs/content/{6.deployment/presets => 3.docs/5.deployment/zz.presets}/lambda.md (100%) rename docs/content/{6.deployment/presets => 3.docs/5.deployment/zz.presets}/node.md (100%) create mode 100644 docs/content/3.docs/5.deployment/zz.presets/server.md rename docs/content/{6.deployment/presets => 3.docs/5.deployment/zz.presets}/service-worker.md (100%) create mode 100644 docs/content/3.docs/index.md delete mode 100644 docs/content/3.server/1.intro.md delete mode 100644 docs/content/3.server/2.api.md delete mode 100644 docs/content/3.server/3.middleware.md rename docs/content/{99.community => 4.community}/1.getting-help.md (100%) rename docs/content/{99.community => 4.community}/2.reporting-bugs.md (100%) rename docs/content/{99.community => 4.community}/3.contribution.md (100%) create mode 100644 docs/content/4.community/index.md delete mode 100644 docs/content/4.modules/1.intro.md delete mode 100644 docs/content/6.deployment/1.platforms.md delete mode 100644 docs/content/6.deployment/presets/server.md delete mode 100644 docs/content/7.bridge/1.intro.md delete mode 100644 docs/content/7.bridge/2.migration.md delete mode 100644 docs/content/8.internals/1.how.md delete mode 100644 docs/content/8.internals/2.code.md delete mode 100644 docs/content/8.internals/3.contrib.md create mode 100644 docs/content/_collections/header.md create mode 100644 docs/content/index.md create mode 100644 docs/plugins/mq.js create mode 100644 docs/static/3D/gem.gltf create mode 100644 docs/static/3D/roughness.jpeg create mode 100644 docs/static/img/home/hero/gem-1.svg create mode 100644 docs/static/img/home/hero/gem-2.svg create mode 100644 docs/static/img/home/hero/gem-3.svg create mode 100644 docs/static/img/home/hero/gem-4.svg create mode 100644 docs/static/img/home/hero/gem-5.svg create mode 100644 docs/static/img/home/hero/gem-6.svg create mode 100644 docs/windi.config.js diff --git a/.eslintignore b/.eslintignore index 125155c9ed..fcffee1acc 100644 --- a/.eslintignore +++ b/.eslintignore @@ -3,3 +3,4 @@ node_modules schema **/*.tmpl.* sw.js +docs diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fa07ca6d59..a67513a4af 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -7,24 +7,23 @@ Please carefully read the contribution docs before creating a pull request ### 🔗 Linked issue - -#... + ### ❓ Type of change - + -- [ ] Documentation (updates to the documentation or readme) -- [ ] Bug fix (a non-breaking change that fixes an issue) -- [ ] Enhancement (improving an existing functionality like performance) -- [ ] New feature (a non-breaking change that adds functionality) -- [ ] Breaking change (fix or feature that would cause existing functionality to change) +- [ ] 📖 Documentation (updates to the documentation or readme) +- [ ] 🐞 Bug fix (a non-breaking change that fixes an issue) +- [ ] 👌 Enhancement (improving an existing functionality like performance) +- [ ] ✨ New feature (a non-breaking change that adds functionality) +- [ ] ⚠️ Breaking change (fix or feature that would cause existing functionality to change) ### 📚 Description - + ### 📝 Checklist diff --git a/README.md b/README.md index 7bc5f5df42..c03ebd37d5 100644 --- a/README.md +++ b/README.md @@ -44,17 +44,28 @@ Welcome to Nuxt3 repository ✨ - -## 👀 Private beta - -We are currently in private beta in order to stabilize the framework before opening to the whole community. - -Please take a look at the [beta discussion](https://github.com/nuxt/framework/discussions/434) for further information. - ## 💻 Development - Clone repository - Ensure you have the latest LTS version of Node.js installed -- Install dependencies with `yarn install` -- Run `yarn stub` to activate passive development -- Open playground with `yarn play` +- Install dependencies with `npx yarn install` +- Run `npx yarn stub` to activate passive development +- Open playground with `npx yarn play` + +Learn more about in our documentation on [how to contribute to Nuxt](https://v3.nuxtjs.org/community/contribution). + +## 📖 Documentation + +We are using [Docus](https://nuxtlabs.com/docus) for documentation (*It is planned to be open sourced it in the following weeks*). + +We recommend to install the [Docus extension](https://marketplace.visualstudio.com/items?itemName=NuxtLabs.docus) for VS Code. + +- Go into the docs directory: `cd docs` +- Install docs dependencies with `npx yarn install` +- Run `npx yarn dev` to start Docus in development mode + +The pages are generated from [docs/content/](./docs/content), you can start editing them to start helping us on documenting Nuxt 3 💚 + +## License + +[MIT](https://github.com/nuxt/nuxt.js/blob/dev/LICENSE) diff --git a/docs/.gitignore b/docs/.gitignore index b8e65d1360..1c12cf9bd4 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1 @@ -5.config schema diff --git a/docs/assets/nuxt.css b/docs/assets/nuxt.css new file mode 100644 index 0000000000..1cb8f98642 --- /dev/null +++ b/docs/assets/nuxt.css @@ -0,0 +1,26 @@ +:root { + --header-height: theme('spacing.14'); + --docs-scroll-margin-block: calc(var(--header-height) + 4rem); + --blogpost-scroll-margin-block: calc(var(--header-height)); +} + +@screen md { + :root { + --header-height: theme('spacing.18'); + --blogpost-scroll-margin-block: calc(var(--header-height) - 0.5rem); + } +} + +@screen xl { + :root { + --docs-scroll-margin-block: calc(var(--header-height) + 1rem); + } +} + +button:focus-visible, div:focus-visible, a:focus-visible { + /* remove default focus style */ + outline: none; + /* custom focus style */ + border-radius: 2px; + box-shadow: 0 0 0 2px #00DC82; +} diff --git a/docs/components/Logo.vue b/docs/components/Logo.vue deleted file mode 100644 index 6d0a64ab29..0000000000 --- a/docs/components/Logo.vue +++ /dev/null @@ -1,25 +0,0 @@ - - - diff --git a/docs/components/app/AppAside.vue b/docs/components/app/AppAside.vue new file mode 100644 index 0000000000..9e080164bc --- /dev/null +++ b/docs/components/app/AppAside.vue @@ -0,0 +1,118 @@ + + + diff --git a/docs/components/app/AppFooter.vue b/docs/components/app/AppFooter.vue new file mode 100644 index 0000000000..818455022e --- /dev/null +++ b/docs/components/app/AppFooter.vue @@ -0,0 +1,31 @@ + + + diff --git a/docs/components/app/AppHeader.vue b/docs/components/app/AppHeader.vue new file mode 100644 index 0000000000..ece0000cc2 --- /dev/null +++ b/docs/components/app/AppHeader.vue @@ -0,0 +1,62 @@ + + + diff --git a/docs/components/app/AppLayout.vue b/docs/components/app/AppLayout.vue new file mode 100644 index 0000000000..6d13cfc2ac --- /dev/null +++ b/docs/components/app/AppLayout.vue @@ -0,0 +1,39 @@ + + + diff --git a/docs/components/app/AsideHeaderNavigation.vue b/docs/components/app/AsideHeaderNavigation.vue new file mode 100644 index 0000000000..8d1ed50cd8 --- /dev/null +++ b/docs/components/app/AsideHeaderNavigation.vue @@ -0,0 +1,71 @@ + + + diff --git a/docs/components/app/AsideNavigation.vue b/docs/components/app/AsideNavigation.vue new file mode 100644 index 0000000000..a5658ea673 --- /dev/null +++ b/docs/components/app/AsideNavigation.vue @@ -0,0 +1,100 @@ + + + diff --git a/docs/components/atoms/Alert.vue b/docs/components/atoms/Alert.vue new file mode 100644 index 0000000000..d70fee5df0 --- /dev/null +++ b/docs/components/atoms/Alert.vue @@ -0,0 +1,121 @@ + + + + + diff --git a/docs/components/atoms/ButtonLink.vue b/docs/components/atoms/ButtonLink.vue new file mode 100644 index 0000000000..d422eda4a5 --- /dev/null +++ b/docs/components/atoms/ButtonLink.vue @@ -0,0 +1,46 @@ + + + + + diff --git a/docs/components/atoms/Gem.vue b/docs/components/atoms/Gem.vue new file mode 100644 index 0000000000..de60f9586f --- /dev/null +++ b/docs/components/atoms/Gem.vue @@ -0,0 +1,121 @@ + +.webgl { + outline: none; +} + + + diff --git a/docs/components/atoms/GitHubButton.vue b/docs/components/atoms/GitHubButton.vue new file mode 100644 index 0000000000..bc51d69e85 --- /dev/null +++ b/docs/components/atoms/GitHubButton.vue @@ -0,0 +1,5 @@ + diff --git a/docs/components/atoms/Headline.vue b/docs/components/atoms/Headline.vue new file mode 100644 index 0000000000..295a4ae0d7 --- /dev/null +++ b/docs/components/atoms/Headline.vue @@ -0,0 +1,5 @@ + diff --git a/docs/components/atoms/Logo.vue b/docs/components/atoms/Logo.vue new file mode 100644 index 0000000000..5c02cbad31 --- /dev/null +++ b/docs/components/atoms/Logo.vue @@ -0,0 +1,26 @@ + + + diff --git a/docs/components/atoms/NuxtContainer.vue b/docs/components/atoms/NuxtContainer.vue new file mode 100644 index 0000000000..58600dd5da --- /dev/null +++ b/docs/components/atoms/NuxtContainer.vue @@ -0,0 +1,18 @@ + + + diff --git a/docs/components/atoms/SectionButton.vue b/docs/components/atoms/SectionButton.vue new file mode 100644 index 0000000000..b9ab20b1f5 --- /dev/null +++ b/docs/components/atoms/SectionButton.vue @@ -0,0 +1,84 @@ + + + diff --git a/docs/components/atoms/Star.vue b/docs/components/atoms/Star.vue new file mode 100644 index 0000000000..0628cb9a7a --- /dev/null +++ b/docs/components/atoms/Star.vue @@ -0,0 +1,45 @@ + + + + diff --git a/docs/components/atoms/TwitterButton.vue b/docs/components/atoms/TwitterButton.vue new file mode 100644 index 0000000000..6bb85a9305 --- /dev/null +++ b/docs/components/atoms/TwitterButton.vue @@ -0,0 +1,5 @@ + diff --git a/docs/components/atoms/icons/IconCAPI.vue b/docs/components/atoms/icons/IconCAPI.vue new file mode 100644 index 0000000000..747973e78c --- /dev/null +++ b/docs/components/atoms/icons/IconCAPI.vue @@ -0,0 +1,3 @@ + diff --git a/docs/components/atoms/icons/IconCLI.vue b/docs/components/atoms/icons/IconCLI.vue new file mode 100644 index 0000000000..f409de1626 --- /dev/null +++ b/docs/components/atoms/icons/IconCLI.vue @@ -0,0 +1,13 @@ + diff --git a/docs/components/atoms/icons/IconClose.vue b/docs/components/atoms/icons/IconClose.vue new file mode 100644 index 0000000000..513b9f1678 --- /dev/null +++ b/docs/components/atoms/icons/IconClose.vue @@ -0,0 +1,5 @@ + diff --git a/docs/components/atoms/icons/IconCode.vue b/docs/components/atoms/icons/IconCode.vue new file mode 100644 index 0000000000..49493d34fa --- /dev/null +++ b/docs/components/atoms/icons/IconCode.vue @@ -0,0 +1,3 @@ + diff --git a/docs/components/atoms/icons/IconDevtools.vue b/docs/components/atoms/icons/IconDevtools.vue new file mode 100644 index 0000000000..eefbcefb49 --- /dev/null +++ b/docs/components/atoms/icons/IconDevtools.vue @@ -0,0 +1,13 @@ + diff --git a/docs/components/atoms/icons/IconDirectory.vue b/docs/components/atoms/icons/IconDirectory.vue new file mode 100644 index 0000000000..bd4639ddf5 --- /dev/null +++ b/docs/components/atoms/icons/IconDirectory.vue @@ -0,0 +1,4 @@ + + diff --git a/docs/components/atoms/icons/IconFeather.vue b/docs/components/atoms/icons/IconFeather.vue new file mode 100644 index 0000000000..873fdf78b6 --- /dev/null +++ b/docs/components/atoms/icons/IconFeather.vue @@ -0,0 +1,13 @@ + diff --git a/docs/components/atoms/icons/IconFile.vue b/docs/components/atoms/icons/IconFile.vue new file mode 100644 index 0000000000..72ebd4eac0 --- /dev/null +++ b/docs/components/atoms/icons/IconFile.vue @@ -0,0 +1,4 @@ + + diff --git a/docs/components/atoms/icons/IconFileSettings.vue b/docs/components/atoms/icons/IconFileSettings.vue new file mode 100644 index 0000000000..07d3bb19af --- /dev/null +++ b/docs/components/atoms/icons/IconFileSettings.vue @@ -0,0 +1,4 @@ + + diff --git a/docs/components/atoms/icons/IconGit.vue b/docs/components/atoms/icons/IconGit.vue new file mode 100644 index 0000000000..06c288415f --- /dev/null +++ b/docs/components/atoms/icons/IconGit.vue @@ -0,0 +1,4 @@ + + diff --git a/docs/components/atoms/icons/IconGitHub.vue b/docs/components/atoms/icons/IconGitHub.vue new file mode 100644 index 0000000000..9f0c4a7041 --- /dev/null +++ b/docs/components/atoms/icons/IconGitHub.vue @@ -0,0 +1,10 @@ + diff --git a/docs/components/atoms/icons/IconHybrid.vue b/docs/components/atoms/icons/IconHybrid.vue new file mode 100644 index 0000000000..46624fec5a --- /dev/null +++ b/docs/components/atoms/icons/IconHybrid.vue @@ -0,0 +1,13 @@ + diff --git a/docs/components/atoms/icons/IconKit.vue b/docs/components/atoms/icons/IconKit.vue new file mode 100644 index 0000000000..8b5dd9d799 --- /dev/null +++ b/docs/components/atoms/icons/IconKit.vue @@ -0,0 +1,12 @@ + diff --git a/docs/components/atoms/icons/IconNpm.vue b/docs/components/atoms/icons/IconNpm.vue new file mode 100644 index 0000000000..b9771cf5b8 --- /dev/null +++ b/docs/components/atoms/icons/IconNpm.vue @@ -0,0 +1,3 @@ + diff --git a/docs/components/atoms/icons/IconNuxtBridge.vue b/docs/components/atoms/icons/IconNuxtBridge.vue new file mode 100644 index 0000000000..fd15c5b58f --- /dev/null +++ b/docs/components/atoms/icons/IconNuxtBridge.vue @@ -0,0 +1,3 @@ + diff --git a/docs/components/atoms/icons/IconNuxtNitro.vue b/docs/components/atoms/icons/IconNuxtNitro.vue new file mode 100644 index 0000000000..2201a1f77d --- /dev/null +++ b/docs/components/atoms/icons/IconNuxtNitro.vue @@ -0,0 +1,3 @@ + diff --git a/docs/components/atoms/icons/IconRabbit.vue b/docs/components/atoms/icons/IconRabbit.vue new file mode 100644 index 0000000000..f02662dab3 --- /dev/null +++ b/docs/components/atoms/icons/IconRabbit.vue @@ -0,0 +1,13 @@ + diff --git a/docs/components/atoms/icons/IconSuspense.vue b/docs/components/atoms/icons/IconSuspense.vue new file mode 100644 index 0000000000..d1b6b20ecf --- /dev/null +++ b/docs/components/atoms/icons/IconSuspense.vue @@ -0,0 +1,13 @@ + diff --git a/docs/components/atoms/icons/IconTwitter.vue b/docs/components/atoms/icons/IconTwitter.vue new file mode 100644 index 0000000000..e2ee131519 --- /dev/null +++ b/docs/components/atoms/icons/IconTwitter.vue @@ -0,0 +1,10 @@ + diff --git a/docs/components/atoms/icons/IconTypeScript.vue b/docs/components/atoms/icons/IconTypeScript.vue new file mode 100644 index 0000000000..b575daef45 --- /dev/null +++ b/docs/components/atoms/icons/IconTypeScript.vue @@ -0,0 +1,3 @@ + diff --git a/docs/components/atoms/icons/IconVite.vue b/docs/components/atoms/icons/IconVite.vue new file mode 100644 index 0000000000..5b2c4cb0d8 --- /dev/null +++ b/docs/components/atoms/icons/IconVite.vue @@ -0,0 +1,3 @@ + diff --git a/docs/components/atoms/icons/IconVue.vue b/docs/components/atoms/icons/IconVue.vue new file mode 100644 index 0000000000..9e0430acc1 --- /dev/null +++ b/docs/components/atoms/icons/IconVue.vue @@ -0,0 +1,3 @@ + diff --git a/docs/components/atoms/icons/IconWebpack.vue b/docs/components/atoms/icons/IconWebpack.vue new file mode 100644 index 0000000000..ac1ccd8a5e --- /dev/null +++ b/docs/components/atoms/icons/IconWebpack.vue @@ -0,0 +1,13 @@ + diff --git a/docs/components/molecules/HeroParallax.vue b/docs/components/molecules/HeroParallax.vue new file mode 100644 index 0000000000..e13de5501b --- /dev/null +++ b/docs/components/molecules/HeroParallax.vue @@ -0,0 +1,58 @@ + + + diff --git a/docs/components/molecules/HeroSection.vue b/docs/components/molecules/HeroSection.vue new file mode 100644 index 0000000000..c98af1374e --- /dev/null +++ b/docs/components/molecules/HeroSection.vue @@ -0,0 +1,33 @@ + diff --git a/docs/components/molecules/HomeHero.vue b/docs/components/molecules/HomeHero.vue new file mode 100644 index 0000000000..b371cffa26 --- /dev/null +++ b/docs/components/molecules/HomeHero.vue @@ -0,0 +1,73 @@ + + + diff --git a/docs/components/organisms/HomeFeatures.vue b/docs/components/organisms/HomeFeatures.vue new file mode 100644 index 0000000000..9fc2e92f49 --- /dev/null +++ b/docs/components/organisms/HomeFeatures.vue @@ -0,0 +1,36 @@ + + + diff --git a/docs/components/organisms/SectionContentItem.vue b/docs/components/organisms/SectionContentItem.vue new file mode 100644 index 0000000000..38edd541bc --- /dev/null +++ b/docs/components/organisms/SectionContentItem.vue @@ -0,0 +1,70 @@ + + + diff --git a/docs/components/templates/Blank.vue b/docs/components/templates/Blank.vue new file mode 100644 index 0000000000..c710b5c35d --- /dev/null +++ b/docs/components/templates/Blank.vue @@ -0,0 +1,16 @@ + + + diff --git a/docs/components/templates/Error.vue b/docs/components/templates/Error.vue new file mode 100644 index 0000000000..b974cf303b --- /dev/null +++ b/docs/components/templates/Error.vue @@ -0,0 +1,33 @@ + + + diff --git a/docs/content/0.index.md b/docs/content/0.index.md deleted file mode 100644 index e15acbc3ac..0000000000 --- a/docs/content/0.index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -layout.aside: true -navigation.hidden: true -navigation.redirect: /get-started/installation ---- - diff --git a/docs/content/1.get-started/1.installation.md b/docs/content/1.get-started/1.installation.md deleted file mode 100644 index d6a99fd5d1..0000000000 --- a/docs/content/1.get-started/1.installation.md +++ /dev/null @@ -1,49 +0,0 @@ -# Installation - -Getting started with Nuxt3 is straightforward. - -💡 Do you want to experience and prepare your project for Nuxt 3 without breaking changes? Check out [Nuxt Bridge](/bridge/intro) page! - -## Prerequisites - -Before installing Nuxt, you'll need to have a local development environment. - -Recommended setup is: - -* **Node.js** * (latest LTS version) [[Download](https://nodejs.org/en/download/)] -* **Visual Studio Code** [[Download](https://code.visualstudio.com/)] -* **Volar extension** [[Download](https://marketplace.visualstudio.com/items?itemName=johnsoncodehk.volar)] -* **Yarn package manager** [[Download](https://classic.yarnpkg.com/en/docs/install#windows-stable)] - -* If you already have Node.js installed, check with `node --version` to ensure using `v14` or `v16`. - - -## Create project - -From visual studio code, open an [integrated terminal](https://code.visualstudio.com/docs/editor/integrated-terminal) and use the following command to create a new starter project: - -```bash -npx nuxi init my-nuxt3-project -``` - -Open `my-nuxt3-project` folder in visual studio code: - -```bash -code -r my-nuxt3-project -``` - -Install dependencies using yarn: - -```bash -yarn install -``` - -## Start Development Server - -Now you'll be able to use `yarn dev` to start nuxt app in development mode: - -```bash -yarn dev -o -``` - -✨Well done! A browser window should automatically open to `http://localhost:3000` diff --git a/docs/content/1.get-started/2.structure.md b/docs/content/1.get-started/2.structure.md deleted file mode 100644 index 50cf476c8e..0000000000 --- a/docs/content/1.get-started/2.structure.md +++ /dev/null @@ -1,52 +0,0 @@ -# Directory Structure - -The Nuxt application structure is intended to provide a great starting point for both small and large applications. You are free to organize your application however you like and can create them as and when you need. - -### The `app.vue` file - -The `app.vue` file, is used as main component for your application ([learn more](/app/app)). - -### The `pages/` directory - -The `pages/` directory contains your application's views and routes. If it exists, Nuxt reads all the `.vue` files inside this directory and uses them to create the application router ([learn more](/app/pages)). - -### The `plugins/` directory - -Nuxt will automatically read the files in your `plugins/` directory and load them. ([learn more](/app/plugins)). - - -### The `server/` directory - -The `server/` directory contains API endpoints and server middleware for your project. ([learn more](/server/api)). - -### The `components/` directory - -The `components/` directory is where you put all your Vue components which can then be imported inside your pages or other components. - -### The `assets/` directory - -The `assets/` directory contains your uncompiled assets such as your styles or fonts. - -### The `static/` directory - -The `static/` directory is directly served at server root and contains public files that have to keep their names (e.g. `robots.txt`) _or_ likely won't change (e.g. `favicon.ico`). - -### The `nuxt.config` file - -The `nuxt.config` (`js` or `ts`) file is the single point of configuration for Nuxt. If you want to add modules or override default settings, this is the place to apply the changes. - -### The `package.json` file - -The `package.json` file contains all the dependencies and scripts for your application. - -### The `yarn.lock` or `package.lock.json` file - -This file is automatically generated and keeps exactly installed version of packages. So that next time you or another one wants to try project, will install same versions. - -### The `.nuxt` directory - -This is the directory used by nuxt to put temporary build files. - -### The `.output` directory - -When using `nuxt build`, this directory will be created and is meant to be deployed to production server. diff --git a/docs/content/1.getting-started/1.introduction.md b/docs/content/1.getting-started/1.introduction.md new file mode 100644 index 0000000000..76e1428369 --- /dev/null +++ b/docs/content/1.getting-started/1.introduction.md @@ -0,0 +1,59 @@ +# Introduction + +## ❓ What is Nuxt? + +Is it the first time Learning about Nuxt or want to get familiar to the new Concepts or Nuxt 3, then we recommand to read the [Concepts section](/concepts) + +## 🛠️ Prerequisites + +Before getting started, please make sure you have installed recommended development software. + +* **Node.js*** (latest LTS version) 👉 [[Download](https://nodejs.org/en/download/)] +* **Visual Studio Code** 👉 [[Download](https://code.visualstudio.com/)] +* **Volar Extension** 👉 [[Download](https://marketplace.visualstudio.com/items?itemName=johnsoncodehk.volar)] + +* If you already have Node.js installed, check with `node --version` to ensure using `v14` or `v16`. + +## 🌉 Bridge or Nuxt 3 + +You must decide if you are starting from scratch or upgrading an existing Nuxt 2 project. + +### 🌱 I am starting a fresh Nuxt project + +- Enjoy using latest Vue 3 +- All of new composables are available +- New templating system and conventions are enabled + +👉 You can go to the [Installation section](/getting-started/installation). + +### ⬆️ I have an existing Nuxt 2 project + +If you have an existing Nuxt 2 project, we **strongly recommend** to start migrating your Nuxt 2 project with Bridge module. This way you can try most of new features without opting-in to more breaking changes. + +- It is risk-free! You can roll back by just commenting out one line in config +- Makes your project almost ready for nuxt3 migration +- Enjoy new DX improvements without major rewrites for vue3 +- Use nitro engine for platform agnostic and optimized deployments +- Help us stabilize nuxt3 and discover flows +- Bridge is more stable than nuxt3 at the moment for migration + +👉 You can go to the [Bridge installation section](/getting-started/installation). + +### ‍⚖️ Comparation + +In the table below, there is a quick comparison between 3 versions of nuxt: + +Feature / Version | Nuxt 2 | Nuxt Bridge | Nuxt 3 +-------------------------|-----------------|------------------|--------- +Stability | 😸 Stable | 😺 Semi Stable | 🙀 Unstable +Performance | 👎 Slower | 👍 Enhanced | 🔥 Fastest +Nitro Engine | ❌ | ✅ | ✅ +ESM support | 🌙 Partial | 👍 Better | ✅ +TypeScript | ☑️ Opt-in | 🚧 Faster | ✅ +Composition API | ⚠️ Deprecated | ✅ | ✅ +Components Auto Import | ✅ | ✅ | ✅ +` - - -``` diff --git a/docs/content/2.concepts/1.introduction.md b/docs/content/2.concepts/1.introduction.md new file mode 100644 index 0000000000..de2413588b --- /dev/null +++ b/docs/content/2.concepts/1.introduction.md @@ -0,0 +1,2 @@ +# An introduction to Nuxt + diff --git a/docs/content/2.concepts/2.server-engine.md b/docs/content/2.concepts/2.server-engine.md new file mode 100644 index 0000000000..592d109c78 --- /dev/null +++ b/docs/content/2.concepts/2.server-engine.md @@ -0,0 +1,55 @@ +# Server Engine + +Nuxt 3 is powered by a new server engine, code-named "Nitro". + +This engine has many benefits: +::list +- Cross-platform support for Node.js, Browsers, service-workers and more +- Serverless support out-of-the-box +- API routes support +- Automatic code-splitting and async-loaded chunks +- Hybrid mode for static + serverless sites +- Development server with hot module reloading +:: + +## API Layer + +Server [API endpoints](/docs/directory-structure/server#api-routes) and [Middleware](/docs/directory-structure/server#server-middleware) are added by Nitro that internally uses [h3](https://github.com/unjs/h3). + +There are a number of key features, including: + +* Handlers can directly return objects/arrays for an automatically-handled JSON response +* Handlers can return promises, which will be awaited (`res.end()` and `next()` are also supported) +* Helper functions for body parsing, cookie handling, redirects, headers and more + +Check out [the h3 docs](https://github.com/unjs/h3) for more information. + + +::alert{type="info" icon=ℹ️} +Learn more about the API layer in the [`server/`](/docs/directory-structure/server) directory. +:: + +## Direct API calls + +Nitro allows 'direct' calling of routes via the globally-available `$fetch` helper. This will make an API call to the server if run on the browser, but will simply call the relevant function if run on the server, **saving an additional API call**. + +`$fetch` API is using [ohmyfetch](https://github.com/unjs/ohmyfetch), with key features including: + +* Automatic parsing of JSON responses (with access to raw response if needed) +* Request body and params are automatically handled, with correct `Content-Type` headers being added + +For more information on `$fetch` features, check out [ohmyfetch](https://github.com/unjs/ohmyfetch). + +## Standalone Server + +Nitro produces a standalone server dist that is independent of `node_modules`. + +The server in Nuxt 2 is not standalone, but requires part of nuxt core to be involved running `nuxt start` (with the [`nuxt-start`](https://www.npmjs.com/package/nuxt-start) or [`nuxt`](https://www.npmjs.com/package/nuxt) distributions) or custom programmatic usage, which was fragile and prone to breakage and not suitable for serverless and service-worker environments. + +This dist is generated when running `nuxt build` into a [`.output`](/docs/directory-structure/output) directory. + +The output is combined with both runtime code to run your Nuxt server in any environment (including experimental browser Service Workers!) and serve you static files, making it a true [hybrid framework](/concepts/hybrid-rendering) for the JAMStack. In addition, a native storage layer is implemented, supporting multi source, drivers and local assets. + +::alert{type="info" icon=IconCode} +Checkout the Nitro engine on GitHub: [framework/packages/nitro](https://github.com/nuxt/framework/tree/main/packages/nitro) +:: diff --git a/docs/content/2.concepts/index.md b/docs/content/2.concepts/index.md new file mode 100644 index 0000000000..e2c77433b9 --- /dev/null +++ b/docs/content/2.concepts/index.md @@ -0,0 +1,7 @@ +--- +title: Concepts +layout.aside: true +layout.asideClass: '' +navigation.exclusive: true +navigation.redirect: /concepts/introduction +--- diff --git a/docs/content/3.docs/1.usage/4.data-fetching.md b/docs/content/3.docs/1.usage/4.data-fetching.md new file mode 100644 index 0000000000..40b837a1e3 --- /dev/null +++ b/docs/content/3.docs/1.usage/4.data-fetching.md @@ -0,0 +1,70 @@ +# Data Fetching + +Nuxt provides `useAsyncData` to handle data fetching within you application. + +## `useAsyncData` + +Within your pages and components you can use `useAsyncData` to get access to data that resolves asynchronously. + +### Usage + +```js +useAsyncData(key: string, fn: () => Object, options?: { defer: boolean, server: boolean }) +``` + +* **key**: a unique key to ensure that data fetching can be properly de-duplicated across requests +* **fn** an asynchronous function that **must return an object**. +* **options**: + - _defer_: whether to load the route before resolving the async function (defaults to `false`) + - _server_: whether the fetch the data on server-side (defaults to `true`) + +Under the hood, `defer: false` uses `` to block the loading of the route before the data has been fetched. Consider using `defer: true` and implementing a loading state instead for a snappier user experience. + +### Example + +```vue + + + +``` + +### Best practices + +As seen in [Concepts > Data fetching](/concepts/data-fetching), the data returned by `useAsyncData` will be stored inside the page payload. This mean that every key returned that is not used in your component will be added to the payload. + +**We strongly recommend to only select the keys that you will use in your component.** + +Imagine that `/api/mountains/everest` returns the following object: + +```json +{ + "title": "Mount Everest", + "description": "Mount Everest is Earth's highest mountain above sea level, located in the Mahalangur Himal sub-range of the Himalayas. The China–Nepal border runs across its summit point", + "height": "8,848 m", + "countries": [ + "China", + "Nepal" + ], + "continent": "Asia", + "image": "https://upload.wikimedia.org/wikipedia/commons/thumb/f/f6/Everest_kalapatthar.jpg/600px-Everest_kalapatthar.jpg" +} +``` + +If you plan to only use `title` and `description` in your component, you can select the keys by chaining the result of `$fetch`: + +```vue + + + +``` diff --git a/docs/content/2.app/4.meta-tags.md b/docs/content/3.docs/1.usage/4.meta-tags.md similarity index 100% rename from docs/content/2.app/4.meta-tags.md rename to docs/content/3.docs/1.usage/4.meta-tags.md diff --git a/docs/content/3.docs/1.usage/index.md b/docs/content/3.docs/1.usage/index.md new file mode 100644 index 0000000000..3977919683 --- /dev/null +++ b/docs/content/3.docs/1.usage/index.md @@ -0,0 +1,7 @@ +--- +title: 'Usage' +layout.aside: true +layout.asideClass: '' +navigation.collapse: true +navigation.redirect: /docs/basics/introduction +--- diff --git a/docs/content/3.docs/2.directory-structure/1.nuxt.md b/docs/content/3.docs/2.directory-structure/1.nuxt.md new file mode 100644 index 0000000000..738e1f764d --- /dev/null +++ b/docs/content/3.docs/2.directory-structure/1.nuxt.md @@ -0,0 +1,16 @@ +--- +icon: IconDirectory +title: '.nuxt' +head.title: Nuxt directory +--- + + +# Nuxt directory + +The `.nuxt` directory is used by Nuxt in development to generate your Vue application. + +::alert{type=warning} +You should not touch any files inside since the whole directory will be re-create when running `nuxt dev` +:: + +This directory is interesting if you want to learn more about the files Nuxt generates based on your directory structure. diff --git a/docs/content/2.app/5.plugins.md b/docs/content/3.docs/2.directory-structure/10.plugins.md similarity index 65% rename from docs/content/2.app/5.plugins.md rename to docs/content/3.docs/2.directory-structure/10.plugins.md index 1ce38bc781..5485afb44b 100644 --- a/docs/content/2.app/5.plugins.md +++ b/docs/content/3.docs/2.directory-structure/10.plugins.md @@ -1,3 +1,9 @@ -# Plugins +--- +icon: IconDirectory +title: 'plugins' +head.title: Plugins directory +--- + +# plugins directory Nuxt will automatically read the files in your `plugins` directory and load them. You can use `.server` or `.client` in the file name to load a plugin just on server- or client-side. diff --git a/docs/content/3.docs/2.directory-structure/11.public.md b/docs/content/3.docs/2.directory-structure/11.public.md new file mode 100644 index 0000000000..620b227b17 --- /dev/null +++ b/docs/content/3.docs/2.directory-structure/11.public.md @@ -0,0 +1,9 @@ +--- +icon: IconDirectory +title: public +head.title: Public directory +--- + +# Public directory + +The `static/` directory is directly served at server root and contains public files that have to keep their names (e.g. `robots.txt`) _or_ likely won't change (e.g. `favicon.ico`). diff --git a/docs/content/3.docs/2.directory-structure/12.server.md b/docs/content/3.docs/2.directory-structure/12.server.md new file mode 100644 index 0000000000..6252488d52 --- /dev/null +++ b/docs/content/3.docs/2.directory-structure/12.server.md @@ -0,0 +1,74 @@ +--- +icon: IconDirectory +title: server +head.title: Server directory +--- + +# Server directory + +The server directory is used to create any backend logic for your Nuxt application. It supports HMR and powerful features. + +The `server/` directory contains API endpoints and server middleware for your project. ([learn more](/server/api)). + +## API Routes + +Nuxt will automatically read in any files in the `~/server/api` directory to create API endpoints. + +Each file should export a default function that handles api requests. It can return a promise or JSON data directly (or use `res.end()`). + +### Examples + +#### Hello world + +```js [server/api/hello.ts] +export default (req, res) => 'Hello World' +``` + +See result on http://localhost:3000/api/hello + +#### Async function + +```js [server/api/async.ts] +export default async (req, res) => { + await someAsyncFunction() + + return { + someData: true + } +} +``` + +**Example:** Using Node.js style + +```ts [server/api/node.ts] +import type { IncomingMessage, ServerResponse } from 'http' + +export default async (req: IncomingMessage, res: ServerResponse) => { + res.statusCode = 200 + res.end('Works!') +} +``` + +## Server Middleware + +Nuxt will automatically read in any files in the `~/server/middleware` to create server middleware for your project. + +These files will be run on every request, unlike [API routes](./api) that are mapped to their own routes. This is typically so you can add a common header to all responses, log responses or modify the incoming request object for use later on in the request chain. + +Each file should export a default function that will handle a request. + +```js +export default async (req, res) => { + req.someValue = true +} +``` + +There is nothing different about the `req`/`res` objects, so typing them is straightforward. + +```ts +import type { IncomingMessage, ServerResponse } from 'http' + +export default async (req: IncomingMessage, res: ServerResponse) => { + req.someValue = true +} +``` diff --git a/docs/content/3.docs/2.directory-structure/13.gitignore.md b/docs/content/3.docs/2.directory-structure/13.gitignore.md new file mode 100644 index 0000000000..fb0c9591f4 --- /dev/null +++ b/docs/content/3.docs/2.directory-structure/13.gitignore.md @@ -0,0 +1,23 @@ +--- +icon: IconFile +title: .gitignore +head.title: Gitignore file +--- + +# Gitignore file + +A `.gitignore` file specifies intentionally untracked files that Git should ignore. Learn more about it on [the git documentation](https://git-scm.com/docs/gitignore). + +We recommand to have a `.gitignore` with **at least** this lines inside: + +```bash [.gitignore] +# Nuxt dev/build outputs +.output +.nuxt +# Node dependencies +node_modules +yarn.lock +package-lock.json +# System files +*.log +``` diff --git a/docs/content/3.docs/2.directory-structure/14.app.md b/docs/content/3.docs/2.directory-structure/14.app.md new file mode 100644 index 0000000000..96e3844bc4 --- /dev/null +++ b/docs/content/3.docs/2.directory-structure/14.app.md @@ -0,0 +1,41 @@ +--- +icon: IconFile +title: app.vue +head.title: App file +--- + +# App file + +The `app.vue` file is the main component in your Nuxt 3 applications. + +## Minimal usage + +With Nuxt 3, the [`pages/`](/docs/directory-structure/pages) directory is optional, if not present, Nuxt won't include [vue-router](https://next.router.vuejs.org/) dependency. This is useful when working on a landing page or an application that does not need routing. + +```vue [app.vue] + +``` + +## Usage with pages + +If you have a [`pages/`](/docs/directory-structure/pages) directory, to display the current page, use the `` component: + +```vue [app.vue] + +``` + +::alert{type=info} +Since Nuxt 3 uses [``](https://v3.vuejs.org/guide/migration/suspense.html) inside ``, we recommend to wrap it into a single root element. +:: + +::alert{type=warning} +Remember that `app.vue` acts as the main component of your Nuxt application, anything you add in it (JS and CSS) will be global and included in every page. +:: + +If you want to have the possibility to customize the structure around the page between pages, checkout the [`layouts/`](/docs/directory-structure/layouts). directory diff --git a/docs/content/3.docs/2.directory-structure/15.nuxt.config.md b/docs/content/3.docs/2.directory-structure/15.nuxt.config.md new file mode 100644 index 0000000000..e3e1af4c28 --- /dev/null +++ b/docs/content/3.docs/2.directory-structure/15.nuxt.config.md @@ -0,0 +1,508 @@ +--- +icon: IconFile +title: nuxt.config.js +head.title: Nuxt configuration file +--- + +# Nuxt configuration file + +Nuxt can be configured easily with one single file, called `nuxt.config`, it supports both `.js` and `.ts` extension. + +```ts +export default { + // My Nuxt config +} +``` + +Learn more about all the different [config properties](/docs/config) + + + +## alias + +- **Type**: `object` +- **Version**: 2, 3 +- **Default** +```json +{ + "~~": "/project", + "@@": "/project", + "~": "/project", + "@": "/project", + "assets": "/project/assets", + "public": "/project" +} +``` + +> You can improve your DX by defining additional aliases to access custom directories within your JavaScript and CSS. + +::alert{type="info"} +**Note**: Within a webpack context (image sources, CSS - but not JavaScript) you _must_ access +your alias by prefixing it with `~`. +:: + +::alert{type="info"} +**Note**: If you are using TypeScript and want to use the alias you define within +your TypeScript files, you will need to add the aliases to your `paths` object within `tsconfig.json` . +:: + +**Example**: +```js +import { resolve } from 'pathe' +export default { + alias: { + 'images': resolve(__dirname, './assets/images'), + 'style': resolve(__dirname, './assets/style'), + 'data': resolve(__dirname, './assets/other/data') + } +} +``` + +## buildDir + +- **Type**: `string` +- **Version**: 2, 3 +- **Default** +```json +"/project/.nuxt" +``` + +> Define the directory where your built Nuxt files will be placed. + +Many tools assume that `.nuxt` is a hidden directory (because it starts with a `.`). If that is a problem, you can use this option to prevent that. + +**Example**: +```js +export default { + buildDir: 'nuxt-build' +} +``` +## buildModules + +- **Type**: `array` +- **Version**: 2, 3 +- **Default** +```json +[] +``` + +> Modules that are only required during development and build time. + +Modules are Nuxt extensions which can extend its core functionality and add endless integrations +Each module is either a string (which can refer to a package, or be a path to a file), a tuple with the module as first string and the options as a second object, or an inline module function. +Nuxt tries to resolve each item in the modules array using node require path (in `node_modules`) and then will be resolved from project `srcDir` if `~` alias is used. + +::alert{type="info"} +**Note**: Modules are executed sequentially so the order is important. +:: + +**Example**: +```js +modules: [ + // Using package name + '@nuxtjs/axios', + // Relative to your project srcDir + '~/modules/awesome.js', + // Providing options + ['@nuxtjs/google-analytics', { ua: 'X1234567' }], + // Inline definition + function () {} +] +``` +::alert{type="info"} +**Note**: Using `buildModules` helps to make production startup faster and also significantly +decreases the size of `node_modules` in production deployments. Please refer to each +module's documentation to see if it is recommended to use `modules` or `buildModules`. +:: + +## dev + +- **Type**: `boolean` +- **Version**: 2, 3 +- **Default** +```json +true +``` + +> Whether Nuxt is running in development mode. + +Normally you should not need to set this. + +## dir + +> Customize default directory structure used by nuxt. + +It is better to stick with defaults unless needed. + + +### `layouts` + +- **Type**: `string` +- **Version**: 2, 3 +- **Default** +```json +"layouts" +``` + +> The layouts directory, each file of which will be auto-registered as a Nuxt layout. + + +### `pages` + +- **Type**: `string` +- **Version**: 2, 3 +- **Default** +```json +"pages" +``` + +> The directory which will be processed to auto-generate your application page routes. + + +### `public` + +- **Type**: `string` +- **Version**: 3 +- **Default** +```json +"public" +``` + +> The directory containing your static files, which will be directly accessible via the Nuxt server and copied across into your `dist` folder when your app is generated. + +## extensions + +- **Type**: `array` +- **Version**: 2, 3 +- **Default** +```json +[ + ".js", + ".mjs", + ".ts", + ".tsx", + ".vue" +] +``` + +> The extensions that should be resolved by the Nuxt resolver. + +## globalName + +- **Type**: `string` +- **Version**: 2, 3 +- **Default** +```json +"nuxt" +``` + +> Allows customizing the global ID used in the main HTML template as well as the main Vue instance name and other options. + +## hooks + +- **Type**: `any` +- **Version**: 2, 3 +- **Default** +```json +null +``` + +> Hooks are listeners to Nuxt events that are typically used in modules, but are also available in `nuxt.config`. + +Internally, hooks follow a naming pattern using colons (e.g., build:done). +For ease of configuration, you can also structure them as an hierarchical object in `nuxt.config` (as below). + +**Example**: +```js +import fs from 'fs' +import path from 'path' +export default { + hooks: { + build: { + done(builder) { + const extraFilePath = path.join( + builder.nuxt.options.buildDir, + 'extra-file' + ) + fs.writeFileSync(extraFilePath, 'Something extra') + } + } + } +} +``` +## modules + +- **Type**: `array` +- **Version**: 2, 3 +- **Default** +```json +[] +``` + +> Modules are Nuxt extensions which can extend its core functionality and add endless integrations + +Each module is either a string (which can refer to a package, or be a path to a file), a tuple with the module as first string and the options as a second object, or an inline module function. +Nuxt tries to resolve each item in the modules array using node require path (in `node_modules`) and then will be resolved from project `srcDir` if `~` alias is used. + +::alert{type="info"} +**Note**: Modules are executed sequentially so the order is important. +:: + +**Example**: +```js +modules: [ + // Using package name + '@nuxtjs/axios', + // Relative to your project srcDir + '~/modules/awesome.js', + // Providing options + ['@nuxtjs/google-analytics', { ua: 'X1234567' }], + // Inline definition + function () {} +] +``` +## privateRuntimeConfig + +- **Type**: `any` +- **Version**: 2, 3 +- **Default** +```json +{} +``` + +> Runtime config allows passing dynamic config and environment variables to the Nuxt app context. + +It is added to the Nuxt payload so there is no need to rebuild to update your configuration in development or if your application is served by the Nuxt server. (For static sites you will still need to regenerate your site to see changes.) +The value of this object is accessible from server only using `$config`. +It will override `publicRuntimeConfig` on the server-side. +It should hold _private_ environment variables (that should not be exposed on the frontend). This could include a reference to your API secret tokens. + +**Example**: +```js +export default { + privateRuntimeConfig: { + apiSecret: process.env.API_SECRET + } +} +``` +## publicRuntimeConfig + +> Runtime config allows passing dynamic config and environment variables to the Nuxt app context. + +It is added to the Nuxt payload so there is no need to rebuild to update your configuration in development or if your application is served by the Nuxt server. (For static sites you will still need to regenerate your site to see changes.) +The value of this object is accessible from both client and server using `$config`. It should hold env variables that are _public_ as they will be accessible on the frontend. This could include a reference to your public URL. + +**Example**: +```js +export default { + publicRuntimeConfig: { + baseURL: process.env.BASE_URL || 'https://nuxtjs.org' + } +} +``` + +### `app` + +- **Type**: `object` +- **Version**: 2, 3 +- **Default** +```json +{ + "basePath": "/", + "assetsPath": "/_nuxt/", + "cdnURL": null +} +``` + +## rootDir + +- **Type**: `string` +- **Version**: 2, 3 +- **Default** +```json +"/project" +``` + +> Define the workspace directory of your application. + +This property can be overwritten (for example, running `nuxt ./my-app/` will set the `rootDir` to the absolute path of `./my-app/` from the current/working directory. +It is normally not needed to configure this option. + +## serverMiddleware + +- **Type**: `array` +- **Version**: 2, 3 +- **Default** +```json +[] +``` + +> Server middleware are connect/express/h3-shaped functions that handle server-side requests. They run on the server and before the Vue renderer. + +By adding entries to `serverMiddleware` you can register additional routes or modify `req`/`res` objects without the need for an external server. +You can pass a string, which can be the name of a node dependency or a path to a file. You can also pass an object with `path` and `handler` keys. (`handler` can be a path or a function.) + +**Example**: +```js +serverMiddleware: [ + // Will register redirect-ssl npm package + 'redirect-ssl', + // Will register file from project server-middleware directory to handle /server-middleware/* requires + { path: '/server-middleware', handler: '~/server-middleware/index.js' }, + // We can create custom instances too + { path: '/static2', handler: serveStatic(__dirname + '/static2') } +] +``` +::alert{type="info"} +**Note**: If you don't want middleware to run on all routes you should use the object +form with a specific path. +:: + + +**Example**: +```js +export default function (req, res, next) { + // req is the Node.js http request object + console.log(req.url) + // res is the Node.js http response object + // next is a function to call to invoke the next middleware + // Don't forget to call next at the end if your middleware is not an endpoint! + next() +} +``` + +**Example**: +```js +const bodyParser = require('body-parser') +const app = require('express')() +app.use(bodyParser.json()) +app.all('/getJSON', (req, res) => { + res.json({ data: 'data' }) +}) +module.exports = app +``` + +**Example**: +```js +export default { + serverMiddleware: { + '/a': '~/server-middleware/a.js', + '/b': '~/server-middleware/b.js', + '/c': '~/server-middleware/c.js' + } +} +``` +## srcDir + +- **Type**: `string` +- **Version**: 2, 3 +- **Default** +```json +"/project" +``` + +> Define the source directory of your Nuxt application. + +If a relative path is specified it will be relative to the `rootDir`. + +**Example**: +```js +export default { + srcDir: 'client/' +} +``` +This would work with the following folder structure: +```bash +-| app/ +---| node_modules/ +---| nuxt.config.js +---| package.json +---| client/ +------| assets/ +------| components/ +------| layouts/ +------| middleware/ +------| pages/ +------| plugins/ +------| static/ +------| store/ +``` +## ssr + +- **Type**: `boolean` +- **Version**: 2, 3 +- **Default** +```json +true +``` + +> Whether to enable rendering of HTML - either dynamically (in server mode) or at generate time. If set to `false` and combined with `static` target, generated pages will simply display a loading screen with no content. + +## watchers + +> The watchers property lets you overwrite watchers configuration in your `nuxt.config`. + + +### `chokidar` + +> Options to pass directly to `chokidar`. + +**See**: [chokidar](https://github.com/paulmillr/chokidar#api) + +#### `ignoreInitial` + +- **Type**: `boolean` +- **Version**: 2, 3 +- **Default** +```json +true +``` + + +### `rewatchOnRawEvents` + +- **Type**: `any` +- **Version**: 2, 3 +- **Default** +```json +{} +``` + +> An array of event types, which, when received, will cause the watcher to restart. + + +### `webpack` + +> `watchOptions` to pass directly to webpack. + +**See**: [webpack@4 watch options](https://v4.webpack.js.org/configuration/watch/#watchoptions). + +#### `aggregateTimeout` + +- **Type**: `number` +- **Version**: 2, 3 +- **Default** +```json +1000 +``` + diff --git a/docs/content/3.docs/2.directory-structure/16.package.md b/docs/content/3.docs/2.directory-structure/16.package.md new file mode 100644 index 0000000000..cc004a0b5a --- /dev/null +++ b/docs/content/3.docs/2.directory-structure/16.package.md @@ -0,0 +1,9 @@ +--- +icon: IconFile +title: package.json +head.title: Package file +--- + +# Package file + +The `package.json` file contains all the dependencies and scripts for your application ([learn more](/docs/directory-structure/package-json)). diff --git a/docs/content/3.docs/2.directory-structure/2.output.md b/docs/content/3.docs/2.directory-structure/2.output.md new file mode 100644 index 0000000000..80ff4a20c2 --- /dev/null +++ b/docs/content/3.docs/2.directory-structure/2.output.md @@ -0,0 +1,15 @@ +--- +icon: IconDirectory +title: '.output' +head.title: Output directory +--- + +# Output directory + +The `.output/` directory is created by Nuxt when building your application for production. + +::alert{type=warning} +You should not touch any files inside since the whole directory will be re-create when running `nuxt build` +:: + +This directory is made to be used when deploying your Nuxt application to production, learn more in our [deployment section](/docs/deployment). diff --git a/docs/content/3.docs/2.directory-structure/3.assets.md b/docs/content/3.docs/2.directory-structure/3.assets.md new file mode 100644 index 0000000000..d67f07f8d2 --- /dev/null +++ b/docs/content/3.docs/2.directory-structure/3.assets.md @@ -0,0 +1,16 @@ +--- +icon: IconDirectory +title: 'assets' +head.title: Assets directory +--- + +# Assets directory + +The `assets/` directory is used to add all the website assets that will be processed by the build tool (Webpack of Vite). + +The directory usually contain such files: +- Stylesheets (CSS, SASS, etc.) +- Fonts +- Images that won't be served from the [public/](/docs/structure/public) directory. + +If you want to serve assets from the server, we recommend to take a look at the [public/](/docs/structure/public) directory. diff --git a/docs/content/3.docs/2.directory-structure/4.components.md b/docs/content/3.docs/2.directory-structure/4.components.md new file mode 100644 index 0000000000..19e981fcf9 --- /dev/null +++ b/docs/content/3.docs/2.directory-structure/4.components.md @@ -0,0 +1,9 @@ +--- +icon: IconDirectory +title: 'components' +head.title: Components directory +--- + +# Components directory + +The `components/` directory is where you put all your Vue components which can then be imported inside your pages or other components ([learn more](/docs/directory-structure/components)). diff --git a/docs/content/3.docs/2.directory-structure/5.composables.md b/docs/content/3.docs/2.directory-structure/5.composables.md new file mode 100644 index 0000000000..f4f33bd7e3 --- /dev/null +++ b/docs/content/3.docs/2.directory-structure/5.composables.md @@ -0,0 +1,9 @@ +--- +icon: IconDirectory +title: 'composables' +head.title: Composables directory +--- + +# Composables directory + +Nuxt will soon support a `composables/` directory to auto import your Vue composables into your application when used, learn more on the [open issue](https://github.com/nuxt/framework/issues/639). diff --git a/docs/content/2.app/2.pages.md b/docs/content/3.docs/2.directory-structure/6.layouts.md similarity index 65% rename from docs/content/2.app/2.pages.md rename to docs/content/3.docs/2.directory-structure/6.layouts.md index 598e8a6e7d..142a6c4e5b 100644 --- a/docs/content/2.app/2.pages.md +++ b/docs/content/3.docs/2.directory-structure/6.layouts.md @@ -1,36 +1,16 @@ -# Pages +--- +icon: IconDirectory +title: 'layouts' +head.title: Layouts directory +--- -Nuxt will automatically integrate [Vue Router](https://next.router.vuejs.org/) and map `pages/` directory into the routes of your application. - -## Dynamic Routes - -If you place anything within square brackets, it will be turned into a [dynamic route](https://next.router.vuejs.org/guide/essentials/dynamic-matching.html) parameter. You can mix and match multiple parameters and even non-dynamic text within a file name or directory. - -### Example - -```bash --| pages/ ----| index.vue ----| users-[group]/ ------| [id].vue -``` - -Given the example above, you can access group/id within your component via the `$route` object: - -```vue - -``` - -## Layouts +# Layouts directory Nuxt provides a customizable layouts framework you can use throughout your application, ideal for extracting common UI or code patterns into reusable layout components. Page layouts are placed in the `layouts/` directory and will be automatically loaded via asynchronous import when used. If you create a `layouts/default.vue` this will be used for all pages in your app. Other layouts are used by setting a `layout` property as part of your component options. -If you have only single layout for application, you can alternatively use (app entry)[/app]. +If you have only single layout for application, you can alternatively use [app.vue](/docs/structure/app). ### Example: a custom layout diff --git a/docs/content/3.docs/2.directory-structure/7.node_modules.md b/docs/content/3.docs/2.directory-structure/7.node_modules.md new file mode 100644 index 0000000000..61185d0117 --- /dev/null +++ b/docs/content/3.docs/2.directory-structure/7.node_modules.md @@ -0,0 +1,7 @@ +--- +icon: IconDirectory +title: 'node_modules' +head.title: Node modules directory +--- + +# Node modules directory diff --git a/docs/content/4.modules/2.kit.md b/docs/content/3.docs/2.directory-structure/8.modules.md similarity index 92% rename from docs/content/4.modules/2.kit.md rename to docs/content/3.docs/2.directory-structure/8.modules.md index 162921f71c..007093a51d 100644 --- a/docs/content/4.modules/2.kit.md +++ b/docs/content/3.docs/2.directory-structure/8.modules.md @@ -1,3 +1,13 @@ +--- +icon: IconDirectory +title: 'modules' +head.title: Local modules directory +--- + +# Local modules directory + +Nuxt has a powerful [modules engine](/concepts/modules). + # Creating Modules Nuxt provides helper functions (accessed from `@nuxt/kit`) to assist in creating modules that can run on both Nuxt 2 and Nuxt 3. @@ -81,3 +91,5 @@ A number of helpers are also provided for use within this context (with more com * extendRoutes Each of these functions provides documentation via IDE hover/autocomplete. + +## Publishing to NPM diff --git a/docs/content/3.docs/2.directory-structure/9.pages.md b/docs/content/3.docs/2.directory-structure/9.pages.md new file mode 100644 index 0000000000..13ce5ac986 --- /dev/null +++ b/docs/content/3.docs/2.directory-structure/9.pages.md @@ -0,0 +1,33 @@ +--- +icon: IconDirectory +title: 'pages' +head.title: Pages directory +--- + +The `pages/` directory is optional, meaning that if you only use [app.vue](/docs/directory-structure/app), vue-router won't be included, reducing your application bundle size. + +# Pages directory + +Nuxt will automatically integrate [Vue Router](https://next.router.vuejs.org/) and map `pages/` directory into the routes of your application. + +## Dynamic Routes + +If you place anything within square brackets, it will be turned into a [dynamic route](https://next.router.vuejs.org/guide/essentials/dynamic-matching.html) parameter. You can mix and match multiple parameters and even non-dynamic text within a file name or directory. + +### Example + +```bash +-| pages/ +---| index.vue +---| users-[group]/ +-----| [id].vue +``` + +Given the example above, you can access group/id within your component via the `$route` object: + +```vue + +``` diff --git a/docs/content/3.docs/2.directory-structure/index.md b/docs/content/3.docs/2.directory-structure/index.md new file mode 100644 index 0000000000..26215000ce --- /dev/null +++ b/docs/content/3.docs/2.directory-structure/index.md @@ -0,0 +1,7 @@ +--- +title: 'Directory structure' +layout.aside: true +layout.asideClass: '' +navigation.collapse: false +navigation.redirect: /docs/directory-structure/app +--- diff --git a/docs/content/6.deployment/platforms/azure-functions.md b/docs/content/3.docs/5.deployment/azure-functions.md similarity index 100% rename from docs/content/6.deployment/platforms/azure-functions.md rename to docs/content/3.docs/5.deployment/azure-functions.md diff --git a/docs/content/6.deployment/platforms/azure.md b/docs/content/3.docs/5.deployment/azure.md similarity index 100% rename from docs/content/6.deployment/platforms/azure.md rename to docs/content/3.docs/5.deployment/azure.md diff --git a/docs/content/6.deployment/platforms/cloudflare.md b/docs/content/3.docs/5.deployment/cloudflare.md similarity index 100% rename from docs/content/6.deployment/platforms/cloudflare.md rename to docs/content/3.docs/5.deployment/cloudflare.md diff --git a/docs/content/6.deployment/platforms/firebase.md b/docs/content/3.docs/5.deployment/firebase.md similarity index 100% rename from docs/content/6.deployment/platforms/firebase.md rename to docs/content/3.docs/5.deployment/firebase.md diff --git a/docs/content/3.docs/5.deployment/index.md b/docs/content/3.docs/5.deployment/index.md new file mode 100644 index 0000000000..2af8f3e610 --- /dev/null +++ b/docs/content/3.docs/5.deployment/index.md @@ -0,0 +1,9 @@ +--- +layout: + aside: true + asideClass: '' +navigation: + collapse: true + exclusive: false + redirect: /docs/deployment/platforms +--- diff --git a/docs/content/6.deployment/platforms/netlify.md b/docs/content/3.docs/5.deployment/netlify.md similarity index 91% rename from docs/content/6.deployment/platforms/netlify.md rename to docs/content/3.docs/5.deployment/netlify.md index 03ebbe98a2..ffff7fc22a 100644 --- a/docs/content/6.deployment/platforms/netlify.md +++ b/docs/content/3.docs/5.deployment/netlify.md @@ -12,7 +12,7 @@ Nitro will auto-detect that you are in a Netlify environment and build the corre ## Deployment -Just push to your git repository [as you would normally for Netlify](https://docs.netlify.com/configure-builds/get-started/). +Just push to your git repository [as you would normally for Netlify](https://docs.netlify.com/configure-builds/getting-started/). ## More information diff --git a/docs/content/6.deployment/platforms/pm2.md b/docs/content/3.docs/5.deployment/pm2.md similarity index 100% rename from docs/content/6.deployment/platforms/pm2.md rename to docs/content/3.docs/5.deployment/pm2.md diff --git a/docs/content/6.deployment/platforms/vercel.md b/docs/content/3.docs/5.deployment/vercel.md similarity index 100% rename from docs/content/6.deployment/platforms/vercel.md rename to docs/content/3.docs/5.deployment/vercel.md diff --git a/docs/content/6.deployment/2.presets.md b/docs/content/3.docs/5.deployment/zz.presets.md similarity index 81% rename from docs/content/6.deployment/2.presets.md rename to docs/content/3.docs/5.deployment/zz.presets.md index 0c94d75db7..2dacd2c4c8 100644 --- a/docs/content/6.deployment/2.presets.md +++ b/docs/content/3.docs/5.deployment/zz.presets.md @@ -1,8 +1,8 @@ -# Presets (advanced) +# [Presets] -There are four provided generic presets for Nuxt Nitro that you can use out-of-the-box: +There are four provided generic presets for Nuxt Nitro that you can use out-of-the-box. -1. [Node.js server](/deployment/presets/server) +1. [Node.js server *(default)*](/deployment/presets/server) 2. [Node.js function](/deployment/presets/node) 3. [Lambda function](/deployment/presets/lambda) 4. [Service worker](/deployment/presets/service-worker) diff --git a/docs/content/6.deployment/presets/99.custom.md b/docs/content/3.docs/5.deployment/zz.presets/custom.md similarity index 100% rename from docs/content/6.deployment/presets/99.custom.md rename to docs/content/3.docs/5.deployment/zz.presets/custom.md diff --git a/docs/content/6.deployment/presets/lambda.md b/docs/content/3.docs/5.deployment/zz.presets/lambda.md similarity index 100% rename from docs/content/6.deployment/presets/lambda.md rename to docs/content/3.docs/5.deployment/zz.presets/lambda.md diff --git a/docs/content/6.deployment/presets/node.md b/docs/content/3.docs/5.deployment/zz.presets/node.md similarity index 100% rename from docs/content/6.deployment/presets/node.md rename to docs/content/3.docs/5.deployment/zz.presets/node.md diff --git a/docs/content/3.docs/5.deployment/zz.presets/server.md b/docs/content/3.docs/5.deployment/zz.presets/server.md new file mode 100644 index 0000000000..46a8590185 --- /dev/null +++ b/docs/content/3.docs/5.deployment/zz.presets/server.md @@ -0,0 +1,63 @@ +# Node.js server + +:ok_hand: **Default preset** if none is specified or auto-detected
+:rocket: Loads only the required chunks to render the request for optimal cold start timing
+:bug: Useful for debugging + +### Usage + +You can use the [Nuxt config](/config) to explicity set the preset to use: + +```ts [nuxt.config.js|ts] +export default { + nitro: { + preset: 'server' + } +} +``` + +Or directly use the `NITRO_PRESET` environment variable when running `nuxt build`: + +```bash +NITRO_PRESET=server npx nuxt build +``` + +### Entrypoint + +When running `nuxt build` with the Node server preset, the result will be an entrypoint that launches a ready-to-run Node server. + +```bash +node .output/server/index.mjs +``` + +### Example + +```bash +$ node .output/server/index.mjs +Listening on http://localhost:3000 +``` + +### Server timings + +You can enable the `nitro.timing` option in order to have the logs about the chunk loading and cold start performance. + +```ts [nuxt.config.js|ts] +export default { + nitro: { + preset: 'server', + timing: true + } +} +``` + +```bash +$ node .output/server/index.mjs +> Cold Start (3ms) +Listening on http://localhost:3000 +> Load chunks/nitro/static (0ms) +> Load chunks/app/render (1ms) +> Load chunks/app/client.manifest (0ms) +> Load chunks/index (3ms) +> Load chunks/app/server (2ms) +> Load chunks/app/vue3 (0ms) +``` diff --git a/docs/content/6.deployment/presets/service-worker.md b/docs/content/3.docs/5.deployment/zz.presets/service-worker.md similarity index 100% rename from docs/content/6.deployment/presets/service-worker.md rename to docs/content/3.docs/5.deployment/zz.presets/service-worker.md diff --git a/docs/content/3.docs/index.md b/docs/content/3.docs/index.md new file mode 100644 index 0000000000..8910808d2a --- /dev/null +++ b/docs/content/3.docs/index.md @@ -0,0 +1,6 @@ +--- +title: Docs +layout.aside: true +navigation.exclusive: true +navigation.redirect: /docs/usage/data-fetching +--- diff --git a/docs/content/3.server/1.intro.md b/docs/content/3.server/1.intro.md deleted file mode 100644 index 858e2c4bde..0000000000 --- a/docs/content/3.server/1.intro.md +++ /dev/null @@ -1,39 +0,0 @@ -# Overview - -Nuxt3 is powered by a new server engine, code-named Nitro. It has: - -- Cross-platform support for Node.js, browser, service-worker targets and more -- Serverless support out-of-the-box -- API routes support -- Automatic code-splitting and async-loaded chunks -- Hybrid mode for static + serverless sites -- A development mode with hot module reloading - -## API Layer - -Server [API endpoints](/server/api) and [Middleware](/server/middleware) are added by Nitro that internally uses [h3](https://github.com/unjs/h3). - -There are a number of key features, including: - -* Handlers can directly return objects/arrays for an automatically-handled JSON response -* Handlers can return promises, which will be awaited (`res.end()` and `next()` are also supported) -* Helper functions for body parsing, cookie handling, redirects, headers and more - - Check out [the h3 docs](https://github.com/unjs/h3) for more information. - -## Direct API calls - -Nitro allows 'direct' calling of routes via the globally-available `$fetch` helper. This will make an API call to the server if run on the browser, but will simply call the relevant function if run on the server, saving an additional API call. - -`$fetch` API is using [ohmyfetch](https://github.com/unjs/ohmyfetch), with key features including: - -* Automatic parsing of JSON responses (with access to raw response if needed) -* Request body and params are automatically handled, with correct `Content-Type` headers being added - -For more information on `$fetch` features, check out [ohmyfetch](https://github.com/unjs/ohmyfetch). - -## Standalone Server - -Nitro produces a standalone server dist that is independent of `node_modules`. - -The server in Nuxt2 is not standalone, but requires part of nuxt core to be involved running `nuxt start` (with the `nuxt-start` or `nuxt` distributions) or custom programmatic usage, which was fragile and prone to breakage and not suitable for serverless and service-worker environments. diff --git a/docs/content/3.server/2.api.md b/docs/content/3.server/2.api.md deleted file mode 100644 index 71bc00b322..0000000000 --- a/docs/content/3.server/2.api.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -navigation: - title: API ---- - -# API Routes - -Nuxt will automatically read in any files in the `~/server/api` directory to create API endpoints. - -Each file should export a default function that handles api requests. It can return a promise or JSON data directly (or use `res.end()`). - -## Examples - -### Hello world - -```js [server/api/hello.ts] -export default (req, res) => 'Hello World' -``` - -See result on http://localhost:3000/api/hello - -### Async function - -```js [server/api/async.ts] -export default async (req, res) => { - await someAsyncFunction() - - return { - someData: true - } -} -``` - -**Example:** Using Node.js style - -```ts [server/api/node.ts] -import type { IncomingMessage, ServerResponse } from 'http' - -export default async (req: IncomingMessage, res: ServerResponse) => { - res.statusCode = 200 - res.end('Works!') -} -``` diff --git a/docs/content/3.server/3.middleware.md b/docs/content/3.server/3.middleware.md deleted file mode 100644 index 45b53f8e63..0000000000 --- a/docs/content/3.server/3.middleware.md +++ /dev/null @@ -1,23 +0,0 @@ -# Server Middleware - -Nuxt will automatically read in any files in the `~/server/middleware` to create server middleware for your project. - -These files will be run on every request, unlike [API routes](./api) that are mapped to their own routes. This is typically so you can add a common header to all responses, log responses or modify the incoming request object for use later on in the request chain. - -Each file should export a default function that will handle a request. - -```js -export default async (req, res) => { - req.someValue = true -} -``` - -There is nothing different about the `req`/`res` objects, so typing them is straightforward. - -```ts -import type { IncomingMessage, ServerResponse } from 'http' - -export default async (req: IncomingMessage, res: ServerResponse) => { - req.someValue = true -} -``` diff --git a/docs/content/99.community/1.getting-help.md b/docs/content/4.community/1.getting-help.md similarity index 100% rename from docs/content/99.community/1.getting-help.md rename to docs/content/4.community/1.getting-help.md diff --git a/docs/content/99.community/2.reporting-bugs.md b/docs/content/4.community/2.reporting-bugs.md similarity index 100% rename from docs/content/99.community/2.reporting-bugs.md rename to docs/content/4.community/2.reporting-bugs.md diff --git a/docs/content/99.community/3.contribution.md b/docs/content/4.community/3.contribution.md similarity index 100% rename from docs/content/99.community/3.contribution.md rename to docs/content/4.community/3.contribution.md diff --git a/docs/content/4.community/index.md b/docs/content/4.community/index.md new file mode 100644 index 0000000000..860bdb9583 --- /dev/null +++ b/docs/content/4.community/index.md @@ -0,0 +1,8 @@ +--- +title: Community +layout.aside: true +layout.asideClass: '' +navigation.collapse: true +navigation.exclusive: true +navigation.redirect: /community/getting-help +--- diff --git a/docs/content/4.modules/1.intro.md b/docs/content/4.modules/1.intro.md deleted file mode 100644 index 496547acea..0000000000 --- a/docs/content/4.modules/1.intro.md +++ /dev/null @@ -1,8 +0,0 @@ -# Nuxt Modules - -Nuxt modules allow encapsulating features and detailed customization of how Nuxt works. You can use them to add features simply within your own project, or publish a library for others to use. - -You can browse through a list of community-provided Nuxt modules at [modules.nuxtjs.org](https://modules.nuxtjs.org/), or via [GitHub discovery](https://github.com/topics/nuxt-module) - -**Note**: -Not all current Nuxt modules are compatible with Nuxt3, in particular modules that have a runtime component. Module authors should consult [the documentation on creating compatible modules](/modules/kit), and please feel free to file an issue on the module repository to track progress. diff --git a/docs/content/6.deployment/1.platforms.md b/docs/content/6.deployment/1.platforms.md deleted file mode 100644 index 2142dd3e55..0000000000 --- a/docs/content/6.deployment/1.platforms.md +++ /dev/null @@ -1,13 +0,0 @@ -# Platforms - -Nuxt Nitro comes with support out-of-the-box for a number of platforms. - -1. [Azure Functions](/deployment/platforms/azure-functions) -1. [Azure Static Web Apps](/deployment/platforms/azure) -1. [Cloudflare](/deployment/platforms/cloudflare) -1. [Firebase](/deployment/platforms/firebase) -1. [Netlify](/deployment/platforms/netlify) -1. [PM2](/deployment/platforms/pm2) -1. [Vercel](/deployment/platforms/vercel) - -We'd welcome pull requests adding support for more, or you can release [a custom preset](/deployment/presets/custom) as a separate package. diff --git a/docs/content/6.deployment/presets/server.md b/docs/content/6.deployment/presets/server.md deleted file mode 100644 index fb47c93ac7..0000000000 --- a/docs/content/6.deployment/presets/server.md +++ /dev/null @@ -1,20 +0,0 @@ -# Node.js server - -- Default preset if none is specified or auto-detected -- Loads only the chunks required to render the request for optimal cold start timing -- Useful for debugging - -### Entrypoint - -With `{ preset: 'server' }` the result will be an entrypoint that launches a ready-to-run Node server. - -#### Example - -```bash -node .output/server/index.mjs -# > Load chunks/nitro/server (10.405923ms) -# > Cold Start (26.289817ms) -# Listening on http://localhost:3000 - -curl http://localhost:3000 -``` diff --git a/docs/content/7.bridge/1.intro.md b/docs/content/7.bridge/1.intro.md deleted file mode 100644 index 70bd08ab96..0000000000 --- a/docs/content/7.bridge/1.intro.md +++ /dev/null @@ -1,82 +0,0 @@ -# Nuxt Bridge - -> ⚠️ This section is work-in-progress and can change. Please check this page regularly. - -Nuxt3 brings a brand-new experience for developing Vue applications. - -To make this happen, we've rewritten most parts of nuxt codebase and are using the latest tooling such as Webpack5, Vite, vue3 and native ESM. -And we've also rethought how nuxt rendering works by introducing the `@nuxt/nitro` project. - -Our goal is a smooth transition path from legacy stack to new one, reducing breaking changes as much as possible. - -To make this happen, we considered backward- and forward-compatibility and most layers (such as modules and plugins). Nonetheless, this is in progress and a bumpy road. - -In the meantime, you can make sure your project is almost ready for nuxt3 and have the latest DX experience without major rewrites and risk of breaking changes by adding a simple module. - -👉 Please see [Migration Guide](./migration) for more details on how you can migrate your nuxt 2 project or module to bridge level. - -## Nuxt 2 vs Nuxt Bridge vs Nuxt 3 - -In the table below, there is a quick comparison between 3 versions of nuxt: - -Feature / Version | Nuxt 2 | Nuxt Bridge | Nuxt 3 --------------------------|-----------------|------------------|--------- -Stability | 😸 Stable | 😺 Semi Stable | 🙀 Unstable -Performance | 👎 Slower | 👍 Enhanced | 🔥 Fastest -Nitro Engine | ❌ | ✅ | ✅ -ESM support | 🌙 Partial | 👍 Better | ✅ -TypeScript | ☑️ Opt-in | 🚧 Faster | ✅ -Composition API | ⚠️ Deprecated | ✅ | ✅ -Components Auto Import | ✅ | ✅ | ✅ -`