From 949e7bce7be2fa80bf8baf6c731c661f99c8e14b Mon Sep 17 00:00:00 2001 From: stefanoslig Date: Tue, 24 Sep 2024 19:53:29 +0200 Subject: [PATCH] documentation --- docs/astro.config.mjs | 27 +++-- .../{index.md => state-management.md} | 2 +- .../content/docs/architecture/structure.md | 104 ++++++++++++++++++ .../index.md | 0 .../index.md => introduction/explanation.md} | 0 .../index.md => introduction/features.md} | 0 .../content/docs/introduction/local-dev.md | 10 ++ 7 files changed, 133 insertions(+), 10 deletions(-) rename docs/src/content/docs/architecture/{index.md => state-management.md} (99%) create mode 100644 docs/src/content/docs/architecture/structure.md rename docs/src/content/docs/{contributions => how-to-contribute}/index.md (100%) rename docs/src/content/docs/{explanation/index.md => introduction/explanation.md} (100%) rename docs/src/content/docs/{features/index.md => introduction/features.md} (100%) create mode 100644 docs/src/content/docs/introduction/local-dev.md diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 47aa75a9..ec1e0465 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -6,25 +6,34 @@ import starlight from '@astrojs/starlight'; export default defineConfig({ integrations: [ starlight({ - logo: {src: './src/assets/logo.png', replacesTitle: true}, + logo: { src: './src/assets/logo.png', replacesTitle: true }, title: 'Angular Realworld App', social: { github: 'https://github.com/stefanoslig/angular-ngrx-nx-realworld-example-app', }, sidebar: [ { - label: 'Angular Realworld App', + label: 'Introduction', items: [ - // Each item here is one entry in the navigation menu. { label: 'Introduction', slug: 'introduction' }, - { label: 'App explanation', slug: 'explanation' }, - { label: 'Angular features', slug: 'features' }, - { label: 'Architecture', slug: 'architecture' }, - { label: 'How to contribute', slug: 'contributions' }, - { label: 'How to run the app locally', slug: 'local-dev' }, + { label: 'App explanation', slug: 'introduction/explanation' }, + { label: 'Angular features', slug: 'introduction/features' }, + { label: 'Run the app locally', slug: 'introduction/local-dev' } + ], + }, + { + label: 'Architecture', + items: [ + { label: 'Folder structure', slug: 'architecture/structure' }, + { label: 'State management', slug: 'architecture/state-management' } + ], + }, + { + label: 'How to contribute', + items: [ + { label: 'How to contribute', slug: 'how-to-contribute' } ], }, - ], }), ], diff --git a/docs/src/content/docs/architecture/index.md b/docs/src/content/docs/architecture/state-management.md similarity index 99% rename from docs/src/content/docs/architecture/index.md rename to docs/src/content/docs/architecture/state-management.md index 76aa76ef..0fc74168 100644 --- a/docs/src/content/docs/architecture/index.md +++ b/docs/src/content/docs/architecture/state-management.md @@ -101,4 +101,4 @@ As you can see in the package.json, we didn't include external libraries, like ` #### Testing -**TBD** \ No newline at end of file +**TBD** diff --git a/docs/src/content/docs/architecture/structure.md b/docs/src/content/docs/architecture/structure.md new file mode 100644 index 00000000..b81af90a --- /dev/null +++ b/docs/src/content/docs/architecture/structure.md @@ -0,0 +1,104 @@ +--- +title: Architecture +description: A guide in my new Starlight docs site. +--- + +### Folders/Libs structure + +For this project I created a monorepo. There is one app for the moment (conduit) which consumes the libraries under the libs folder. + +The folder structure is: + +``` +├── libs +│ ├── articles +│ │ ├── data-access +│ │ ├── feature-article-edit +│ │ ├── feature-article +│ │ ├── feature-articles-list +│ ├── auth +│ │ ├── data-access +│ │ ├── feature-auth +│ ├── core +│ │ ├── api-types +│ │ ├── error-handler +│ │ ├── http-client +│ │ ├── forms +│ ├── profile +│ │ ├── data-access +│ │ ├── feature-profile +│ ├── ui +│ │ ├── components +``` + +I used two classifiers to name my libraries. The first classifier is the `scope` and the second the `type`. The main reason is that I want every developer when he looks a library to understand where this library can be used and which kind of services/components/etc contains. + +The `scope` is the section (domain) of the app the library can be used. It gives a clear indication that a feature belongs to a specific domain. For example the libraries under `users` scope, are used in the users and favourite users pages. The ibraries under the `core` scope can be reused between all the sections of the app. **_The `core` scope will be rename soon to `shared`_**. + +The `type` indicates the purpose of a library. I have used a number of different types (feature, data-access, ui, api-types) The `feature-...` type contains smart components. These are components which enable the communication with the data-sources (most likely they inject api services). The `data-access` type contains code for interacting with the server. The `ui` type contains dumb (presentational) components. These components are reusable in the scope of this library + +### Standalone components + +I have used only standalone components. You won't see any modules in the app. + +### Lazy loaded components + +As you can see from the route configuration, the two main pages in the app are loaded lazily. This will make the initial loading time of the app faster. + +```ts + { + path: '', + redirectTo: 'home', + pathMatch: 'full', +}, +{ + path: 'home', + loadChildren: () => import('@realworld/home/src/lib/home.routes').then((home) => home.HOME_ROUTES), +}, +{ + path: 'login', + loadComponent: () => import('@realworld/auth/feature-auth').then((m) => m.LoginComponent), +}, +{ + path: 'register', + loadComponent: () => import('@realworld/auth/feature-auth').then((m) => m.RegisterComponent), +}, +{ + path: 'article', + loadChildren: () => import('@realworld/articles/article').then((m) => m.ARTICLE_ROUTES), +}, +{ + path: 'settings', + loadComponent: () => + import('@realworld/settings/feature-settings').then((settings) => settings.SettingsComponent), +}, +{ + path: 'editor', + loadChildren: () => import('@realworld/articles/article-edit').then((article) => article.ARTICLE_EDIT_ROUTES), + canActivate: [authGuard], +}, +{ + path: 'profile', + loadChildren: () => import('@realworld/profile/feature-profile').then((profile) => profile.PROFILE_ROUTES), +}, +``` + +### State management + +**TBD** + +### The smart-dumb components design pattern for the components: + +There is a clear distinction in the codebase between the smart and dumb components. The main reason behind this decision is that I want most of my components to be reusable and easier to be tested. That means that they should not have dependencies and they just consume the data they get from the smart component. Also it makes clearer a compoenent's responsibility. + +### Avoid using external dependencies + +As you can see in the package.json, we didn't include external libraries, like `angular-material`, libs for the ui components, state management,etc. The reason is that it might be tempting to use a library like this in the short term to develop something fast, but in the long term they can introduce many problems: + +- opinionated styles +- make the migration to newer versions of Angular more difficult +- not full control on them + +### Testing + +**TBD** diff --git a/docs/src/content/docs/contributions/index.md b/docs/src/content/docs/how-to-contribute/index.md similarity index 100% rename from docs/src/content/docs/contributions/index.md rename to docs/src/content/docs/how-to-contribute/index.md diff --git a/docs/src/content/docs/explanation/index.md b/docs/src/content/docs/introduction/explanation.md similarity index 100% rename from docs/src/content/docs/explanation/index.md rename to docs/src/content/docs/introduction/explanation.md diff --git a/docs/src/content/docs/features/index.md b/docs/src/content/docs/introduction/features.md similarity index 100% rename from docs/src/content/docs/features/index.md rename to docs/src/content/docs/introduction/features.md diff --git a/docs/src/content/docs/introduction/local-dev.md b/docs/src/content/docs/introduction/local-dev.md new file mode 100644 index 00000000..7cb0127d --- /dev/null +++ b/docs/src/content/docs/introduction/local-dev.md @@ -0,0 +1,10 @@ +--- +title: Introduction +description: A guide in my new Starlight docs site. +--- + +This codebase was created to demonstrate a fully fledged fullstack application built with Angular, ngrx/platform, nrwl/nx including CRUD operations, authentication, routing, pagination, and more. + +We've gone to great lengths to adhere to the Angular community styleguides & best practices. + +For more information on how to this works with other frontends/backends, head over to the [RealWorld](https://github.com/gothinkster/realworld) repo.