diff --git a/build-and-run.md b/build-and-run.md index 10109dc0..82fc2df3 100644 --- a/build-and-run.md +++ b/build-and-run.md @@ -23,11 +23,11 @@ For Windows systems use `build.bat`; ## Process -Process consists of 4 stages; +Process consists of 2 stages; -1. Lint checking using eslint -1. [Prebuild][], markdowns are preprocessed in this stage -1. Nuxt build +1. Prepare has 2 stage in itself + 1. Lint checking using eslint + 1. [Prebuild][], markdowns are preprocessed in this stage 1. Last stage differs between `build` & `run` 1. When building, there are two different options 1. It creates a static site for deployment @@ -38,14 +38,12 @@ Process consists of 4 stages; ```mermaid flowchart TB - subgraph nuxtbuild[nuxt build] + subgraph prepare[prepare] direction LR - CB(client build) --> SB(server build) + E(eslint) --> P(prebuild) end - E(eslint) --> P(prebuild) - P --> nuxtbuild - nuxtbuild -->|nuxt generate| SWS(static web site) - nuxtbuild -->|nuxt dev| OS(running on server) + prepare -->|nuxt generate| SWS(static web site) + prepare -->|nuxt dev| OS(running on server) ``` ## `package.json` Configuration diff --git a/migration.md b/change-history/package-upgrades.md similarity index 87% rename from migration.md rename to change-history/package-upgrades.md index 84af22c6..fa2aae20 100644 --- a/migration.md +++ b/change-history/package-upgrades.md @@ -1,23 +1,17 @@ ---- -position: 103 ---- - -# Migration - -## Upgrage package +# Package upgrades for the new version of Nuxt The upgrade sequences are as below. Different errors may occur if the order changes. -### `log-symbols` +## `log-symbols` -#### 5.1.0 +### 5.1.0 Added it because it is needed for the `log` task in `.prebuild`. -### `Node` +## `Node` -#### 20.8.0 +### 20.8.0 When upgrading to this version, version 3.4.1 of nuxt gives run time errors. @@ -35,9 +29,9 @@ not found: "ts.executeCommandLine(ts.sys, ts.noop, ts.sys.args);"". Upgraded the nuxt version to 3.7.4 to fix it. -### `Mermaid-js` +## `Mermaid-js` -#### 10.4.0 +### 10.4.0 Clean upgrade. No issues. @@ -48,9 +42,9 @@ Clean upgrade. No issues. } ``` -### `dotenv` +## `dotenv` -#### 16.3.1 +### 16.3.1 Clean upgrade. No issues. @@ -61,9 +55,9 @@ Clean upgrade. No issues. } ``` -### `eslint-plugin-vue` +## `eslint-plugin-vue` -#### 9.17.0 +### 9.17.0 Clean upgrade. No issues. @@ -74,9 +68,9 @@ Clean upgrade. No issues. } ``` -### `sass` +## `sass` -#### 1.69.2 +### 1.69.2 Clean upgrade. No issues. @@ -87,9 +81,9 @@ Clean upgrade. No issues. } ``` -### `yaml` +## `yaml` -#### 2.3.2 +### 2.3.2 Clean upgrade. No issues. @@ -100,9 +94,9 @@ Clean upgrade. No issues. } ``` -### `webpack` +## `webpack` -#### 5.88.2 +### 5.88.2 Clean upgrade. No issues. @@ -113,9 +107,9 @@ Clean upgrade. No issues. } ``` -### `vue-tsc` +## `vue-tsc` -#### 1.8.19 +### 1.8.19 Clean upgrade. No issues. @@ -126,9 +120,9 @@ Clean upgrade. No issues. } ``` -### `typescript` +## `typescript` -#### 5.2.2 +### 5.2.2 ```json "devDependencies": { @@ -157,9 +151,9 @@ Please only submit bug reports when using the officially supported version. ============= ``` -### `types/node` +## `types/node` -#### 20.8.4 +### 20.8.4 ```json "devDependencies": { @@ -171,9 +165,9 @@ Please only submit bug reports when using the officially supported version. This version of type/node does not work with version 3.4.1 of nuxt. You can downgrade the version or upgrade the version of nuxt for a solution. -### `nuxt` +## `nuxt` -#### 3.7.4 +### 3.7.4 With this version, the generate process fails if the url of the links cannot be generated. So make sure that the target page of the links exists. @@ -183,9 +177,9 @@ to move to a final version nuxt project built with the new nuxt kit. You can see this move by looking at [Move to new project](./setup-guide#move-to-new-project). -### `nuxt Content` +## `nuxt Content` -#### 2.5.2 +### 2.5.2 [nuxt.config.ts] ```ts @@ -196,7 +190,7 @@ content: { } ``` -#### 2.8.5 +### 2.8.5 [nuxt.config.ts] ```ts diff --git a/migrations.md b/migrations.md new file mode 100644 index 00000000..69a147d8 --- /dev/null +++ b/migrations.md @@ -0,0 +1,251 @@ +--- +position: 103 +--- + +# Migrations + +versionlar arası geçiş .... + +## Nuxt: v3.4.1 :point_right: v3.7.4 + +First we tried to upgrade to the new version of nuxt with upgrades, but the +resulting confilicts got too complicated, you can see the upgrade process in +[Package Upgrades](./change-history/package-upgrades.md). So we proceeded by +creating a new nuxt project with the latest version of `nuxt-kit`. + +`npx nuxi@latest init .theme` + +> :information_source: +> +> Before create a new project we recommend to move `.theme` to `.theme-legacy`. + +Replace to this code in `app.vue` + +```vue + +``` + +### Adding Nuxt Content Module + +Add content module + +`npm install @nuxt/content` + +Create new page `[...content-page]` and add this code to under `/pages` directory + +```vue + +``` + +Configure `nuxt.config.ts` + +```ts +export default defineNuxtConfig({ + devtools: { enabled: true }, + modules: [ + '@nuxt/content' + ], + content: { + // ... options + } +}) +``` + +If you have come this far, create a markdown file called `index.md` under the +`/content` folder. Display your page by saying `npm run dev`. + +#### Close `headings.anchorLinks` option + +By default headers come in link format and the render will be as follows. + +```html + +``` + +You can do the following configuration to turn it off and render normal text. + +```ts +export default defineNuxtConfig({ + ... + runtimeConfig: { + public: { + mdc: { + headings: { + anchorLinks: { + h1: false, + h2: false, + h3: false, + h4: false, + h5: false, + h6: false, + }, + }, + }, + }, + }, +}); +``` + +the output is as follows. + +```html + +``` + +### Sass & Css + +You can make these configurations to source css to the project from outside. + +```ts +export default defineNuxtConfig({ + ... + app: { + head: { + ... + link: [ + { + rel: "stylesheet", + type: "text/css", + href: "https://mouseless.github.io/brand/assets/css/default.css" + } + ] + } + }, + css: ["~/assets/styles.css"] +}) +``` + +to export sass files first install sass + +`npm install sass` + +second configure `nuxt.config.ts` + +```ts +export default defineNuxtConfig({ + ... + vite: { + css: { + preprocessorOptions: { + scss: { + additionalData: "@import \"@/assets/variables.scss\";" + } + } + } + }, + css: ["~/assets/styles.scss"] +}) +``` + +put your style files under `/assets` + +### env files + +By adding enverioment files, you can export these files during build and use +your constant values during build or runtime. + +`npx nuxi dev --dotenv .env.local` + +If you write your constant values with the prefix `NUXT` and `NUXT_PUBLIC` in +your env file, nuxt will match them automatically. + +### prebuild + +In the preparation phase with prebuild, we prepare the markdowns at the root +and put them under content. We also prepare the corresponding pages and pull +the markdown content in these pages and render them. + +After `prebuild` make sure that the folder where the public files are moved +from `nuxt.config.ts` is set correctly. + +```ts +export default defineNuxtConfig({ + ... + dir: { + public: ".public" + }, +}) +``` + +### components + +You must do this configuration to access globally when writing and using +the component. + +```ts +export default defineNuxtConfig({ + ... + components: { + dirs: [{ global: true, path: "~/components/Prose" }, "~/components"] + }, +}) +``` + +### new module & nuxt content transformer + +To intervene when `nuxt content` reads markdowns and converts them to html +object, we need to use the `transformer` feature of `nuxt content`, to do +this we need to add it as a module to nuxt. + +Nuxt scans the `/modules` directory and loads them before starting. If you +add them under `/modules`, you don't need to add those local modules to your +`nuxt.config.ts` separately. + +> :warning: +> +> only nuxt modules should be under `/modules`. + +To see the use of transformer `/transformers/optimus-prime.ts` +To see how to add a module look `nuxt.config.ts`. + +### prerender fail + +After version nuxt 3.6.2, if a page corresponding to the link cannot be found, +it gives generate error. + +For solution you can make `nitro.prerender.failOnError` `false` or add path to +`nitro.prerender.ignore` array. + +See `nuxt.config.ts` for example. + +### trailingslash + +With the new nuxt version, the trailing slash solution we found earlier no +longer works. So we removed the solution for trailing slash in +`[...content-page].vue` and the `router.options.strict: true` setting in +`nuxt.config.ts`. + +In the new version, the trailing slash causes problems with images. As a +solution, we saw that the change we made in ProseImg reflected the change made +in the prerender phase. Therefore, we removed the page part from the paths of +the images in the files that are not on the index page in the prerender phase. +In this way, it searches the image under the relevant file. + +See `ProseImg.vue` component in `components/Prose` folder for how to fix +trailing slash issue. + +See here for possible img cases. +[test](./test/index.md) + +### Eslint + +The `@nuxtjs/eslint-config-typescript` module is sufficient by itself, so +other modules have been removed from eslint. + +### Removing the build stage + +Removing the build stage we added in generate. Now nuxt builds itself before +generate. The build script that we want to run before generate has been +removed from the scripts. diff --git a/setup-guide.md b/setup-guide.md index 4f75fc4f..83415dd2 100644 --- a/setup-guide.md +++ b/setup-guide.md @@ -37,244 +37,3 @@ to use under `CHROMIUM_EXECUTABLE_PATH` key. This is where we host the config settings for production mode. Settings in `.env.production` are used when deploying. - -## Move to new project - -First create new nuxt project with latest version - -`npx nuxi@latest init .theme` - -> :information_source: -> -> Before create a new project we recommend to move `.theme` to `.theme-legacy`. - -Replace to this code in `app.vue` - -```vue - -``` - -### Adding Nuxt Content Module - -Add content module - -`npm install @nuxt/content` - -Create new page `[...content-page]` and add this code to under `/pages` directory - -```vue - -``` - -Configure `nuxt.config.ts` - -```ts -export default defineNuxtConfig({ - devtools: { enabled: true }, - modules: [ - '@nuxt/content' - ], - content: { - // ... options - } -}) -``` - -If you have come this far, create a markdown file called `index.md` under the -`/content` folder. Display your page by saying `npm run dev`. - -#### Close `headings.anchorLinks` option - -By default headers come in link format and the render will be as follows. - -```html - -``` - -You can do the following configuration to turn it off and render normal text. - -```ts -export default defineNuxtConfig({ - ... - runtimeConfig: { - public: { - mdc: { - headings: { - anchorLinks: { - h1: false, - h2: false, - h3: false, - h4: false, - h5: false, - h6: false, - }, - }, - }, - }, - }, -}); -``` - -the output is as follows. - -```html - -``` - -### Sass & Css - -You can make these configurations to source css to the project from outside. - -```ts -export default defineNuxtConfig({ - ... - app: { - head: { - ... - link: [ - { - rel: "stylesheet", - type: "text/css", - href: "https://mouseless.github.io/brand/assets/css/default.css" - } - ] - } - }, - css: ["~/assets/styles.css"] -}) -``` - -to export sass files first install sass - -`npm install sass` - -second configure `nuxt.config.ts` - -```ts -export default defineNuxtConfig({ - ... - vite: { - css: { - preprocessorOptions: { - scss: { - additionalData: "@import \"@/assets/variables.scss\";" - } - } - } - }, - css: ["~/assets/styles.scss"] -}) -``` - -put your style files under `/assets` - -### env files - -By adding enverioment files, you can export these files during build and use -your constant values during build or runtime. - -`npx nuxi dev --dotenv .env.local` - -If you write your constant values with the prefix `NUXT` and `NUXT_PUBLIC` in -your env file, nuxt will match them automatically. - -### prebuild - -In the preparation phase with prebuild, we prepare the markdowns at the root -and put them under content. We also prepare the corresponding pages and pull -the markdown content in these pages and render them. - -After `prebuild` make sure that the folder where the public files are moved -from `nuxt.config.ts` is set correctly. - -```ts -export default defineNuxtConfig({ - ... - dir: { - public: ".public" - }, -}) -``` - -### components - -You must do this configuration to access globally when writing and using -the component. - -```ts -export default defineNuxtConfig({ - ... - components: { - dirs: [{ global: true, path: "~/components/Prose" }, "~/components"] - }, -}) -``` - -### new module & nuxt content transformer - -To intervene when `nuxt content` reads markdowns and converts them to html -object, we need to use the `transformer` feature of `nuxt content`, to do -this we need to add it as a module to nuxt. - -Nuxt scans the `/modules` directory and loads them before starting. If you -add them under `/modules`, you don't need to add those local modules to your -`nuxt.config.ts` separately. - -> :warning: -> -> only nuxt modules should be under `/modules`. - -To see the use of transformer `/transformers/optimus-prime.ts` -To see how to add a module look `nuxt.config.ts`. - -### prerender fail - -After version nuxt 3.6.2, if a page corresponding to the link cannot be found, -it gives generate error. - -For solution you can make `nitro.prerender.failOnError` `false` or add path to -`nitro.prerender.ignore` array. - -See `nuxt.config.ts` for example. - -### trailingslash - -With the new nuxt version, the trailing slash solution we found earlier no -longer works. So we removed the solution for trailing slash in -`[...content-page].vue` and the `router.options.strict: true` setting in -`nuxt.config.ts`. - -In the new version, the trailing slash causes problems with images. As a -solution, we saw that the change we made in ProseImg reflected the change made -in the prerender phase. Therefore, we removed the page part from the paths of -the images in the files that are not on the index page in the prerender phase. -In this way, it searches the image under the relevant file. - -See `ProseImg.vue` component in `components/Prose` folder for how to fix -trailing slash issue. - -See here for possible img cases. -[test](./test/index.md) - -### Eslint - -The `@nuxtjs/eslint-config-typescript` module is sufficient by itself, so -other modules have been removed from eslint. - -### Removing the build stage - -Removing the build stage we added in generate. Now nuxt builds itself before -generate. The build script that we want to run before generate has been -removed from the scripts.