diff --git a/doc/pages/commands/_meta.json b/doc/pages/commands/_meta.json index 83e23c6..9a9a12b 100644 --- a/doc/pages/commands/_meta.json +++ b/doc/pages/commands/_meta.json @@ -1,4 +1,5 @@ { "scaffold": "new", + "docs": "docs", "generate": "generate" } diff --git a/doc/pages/commands/docs.mdx b/doc/pages/commands/docs.mdx new file mode 100644 index 0000000..df33f60 --- /dev/null +++ b/doc/pages/commands/docs.mdx @@ -0,0 +1,11 @@ +# Docs + +It allows you to open this documentation website. + +## Get Started + +To open the documentation site you need to launch the command: + +```bash copy +devmy docs +``` diff --git a/doc/pages/commands/generate/addon/angular_tailwind.mdx b/doc/pages/commands/generate/addon/angular_tailwind.mdx new file mode 100644 index 0000000..74b781d --- /dev/null +++ b/doc/pages/commands/generate/addon/angular_tailwind.mdx @@ -0,0 +1,17 @@ +--- +title: angular/tailwind +--- +# Angular/Tailwind + +The Devmy CLI provides a set of predefined configurations that will allow you to start developing right away. + +The addon will take care of installing the necessary dependencies and initializing the library of +[TailwindCSS](https://tailwindcss.com/) so that it is ready to use immediately. + +## Get Started + +To add a new tailwind configuration, use the following Devmy CLI command: + +```bash copy +devmy generate addon angular/tailwind +``` diff --git a/doc/pages/commands/generate/addon/firebase_hosting.mdx b/doc/pages/commands/generate/addon/firebase_hosting.mdx new file mode 100644 index 0000000..02d7a51 --- /dev/null +++ b/doc/pages/commands/generate/addon/firebase_hosting.mdx @@ -0,0 +1,25 @@ +--- +title: firebase/hosting +--- + +# Firebase/Hosting + +The Devmy CLI provides a set of predefined configurations that will allow you to start developing right away. + +The firebase/hosting addon allows you to automatically select and configure applications within the monorepo +to be used as [hosting for Firebase](https://firebase.google.com/docs/hosting). When you run the command, the CLI +will prompt you to choose the application where the changes will be applied, and you'll need to select the project +containing the Firebase configurations. +After that, a list of monorepo applications compatible with this feature will be displayed. + +The plugin will check for any already configured applications to prevent accidental overwrites. + +By selecting the desired applications, the plugin will automatically integrate them into the Firebase configuration. + +## Get Started + +To add a new firebase hosting configuration, use the following Devmy CLI command: + +```bash copy +devmy generate addon firebase/hosting +``` diff --git a/doc/pages/commands/generate/addon/gitlab.mdx b/doc/pages/commands/generate/addon/gitlab.mdx new file mode 100644 index 0000000..03e0937 --- /dev/null +++ b/doc/pages/commands/generate/addon/gitlab.mdx @@ -0,0 +1,158 @@ +# Gitlab + +The Devmy CLI provides a set of predefined configurations that will allow you to start developing right away. + +Gitlab Addon automates the process of setting up the gitlab configuration for +the current workspace, making it ready for CI/CD environment. It will create the +following files automatically: + +1. .gitlab-ci.yml +automatically creates the `.gitlab-ci.yml` file including all the common steps of all the projects defined in the +[Devmy devops project](https://gitlab.com/pillar-1/devops) + +2. Merge request template +automatically creates and configure the `.gitlab/merge_request_templates/merge_request_template.md` file including all +the common sections of all projects + + +**IMPORTANT:** +- Add environment variables: +once the command is finished, it will invite you to configure some environment variables on gitlab. +Do it now or it will be your business and you will have to manually recover them later. + +## Get Started + +To add a new vercel configuration, use the following Devmy CLI command: + +```bash copy +devmy generate addon gitlab +``` + +## Manual configuration + +in case you want to manually configure the gitlab configuration you will have to do following steps. + +### .gitlab-ci.yml + +You will have to insert the `.gitlab-ci.yml` file into +your application. +this is a sample `.gitlab-ci.yml` which is usually applied by this addon: + +```yml filename=".gitlab-ci.yml" copy +include: + - file: /gitlab-ci/common.yml + project: pillar-1/devops + ref: v1.1.6 +``` + +### Merge request + +You will have to create and configure the `.gitlab/merge_request_templates/merge_request_template.md`. +this is a sample `merge_request_template.md` which is usually applied by this addon: + +```markdown filename="merge_request_template.md" copy +## First you have to merge + + + +- [ ] https://gitlab.com/{group}/{project}/-/merge_requests/{id} +- [ ] https://gitlab.com/{group}/{project}/-/merge_requests/{id} +- [ ] https://gitlab.com/{group}/{project}/-/merge_requests/{id} + +## Description + + +... + +**Issue:** [DE-00000](https://app.clickup.com/t/2428116/DE-00000) + +## Screenshots + + + +## Type of change + +- [ ] Bug fix (non-disruptive change that solves a problem) +- [ ] New feature (non-disruptive change that adds new functionality) +- [ ] Breaking change (fix or feature that would prevent existing features from working as intended) +- [ ] Docs (correction or addition of documentation) + +## How was it tested? + + + +- [ ] Test A +- [ ] Test B + +## Checklist: + +- [ ] I have included the task ID in the title of this merge request +- [ ] I aligned my branch with the changes in the `main` branch +- [ ] I did a self-review of my code +- [ ] I commented out my code, especially in hard-to-understand areas +- [ ] I made corresponding changes to the documentation +- [ ] I formatted and sorted the code correctly +- [ ] I've added tests that prove my fix is effective or that my functionality is correct +- [ ] New and existing unit tests pass locally with my changes +``` + +### Semantic Release + +You will have to update the `.releaserc.js` file to work with gitlab. + +install the gitlab plugin for semantic release: + +```bash copy +pnpm i -D @semantic-release/gitlab -w +``` +this is a sample `.releaserc.js` which is usually applied by this addon: + +```js filename=".releaserc.js" copy +const { env } = require('@dotenv-run/core'); + +env({ + files: ['.env.vault'], +}); + +/** + * @type {import('semantic-release').GlobalConfig} + */ +const releaseConfig = { + branches: ["main"], + plugins: [ + "@semantic-release/commit-analyzer", + "@semantic-release/release-notes-generator", + "@semantic-release/changelog", + "@semantic-release/npm", + ["@semantic-release/gitlab", { assets: ["CHANGELOG.md"] }], + [ + "@semantic-release/exec", + { + prepareCmd: "pnpm version ${nextRelease.version} --allow-same-version --no-commit-hooks --no-git-tag-version -ws --no-workspaces-update", + }, + ], + [ + "@semantic-release/git", + { + assets: [ + "CHANGELOG.md", + "package.json", + "package-lock.json", + "applications/**/package.json", + "libraries/**/pnpm-lock.yaml" + ], + message: + "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}", + }, + ], + ], +}; + +module.exports = releaseConfig; +``` diff --git a/doc/pages/commands/generate/addon/vercel.mdx b/doc/pages/commands/generate/addon/vercel.mdx new file mode 100644 index 0000000..acc64ea --- /dev/null +++ b/doc/pages/commands/generate/addon/vercel.mdx @@ -0,0 +1,120 @@ +# Vercel + +The Devmy CLI provides a set of predefined configurations that will allow you to start developing right away. + +Vercel Addon automates the process of setting up the Vercel configuration for +the current application, making it ready for deployment. It performs the +following tasks automatically: + +1. Requests Vercel Tokens: +For both the staging and production environments, you will be asked to +provide their respective Vercel tokens. You can obtain these tokens by +visiting: +https://vercel.com/account/tokens + +2. Updates the CDCI file: +The command will modify your (GitLab CI) configuration to include deployment +steps for both staging and production environments. + +3. Populates .env.vault variables: +The script will automatically insert environment variables into the +.env.vault file for both staging and production. + + +**IMPORTANT:** +- Separate Vercel accounts: +This command assumes that staging and production are hosted on two separate +Vercel accounts. Using the same token for both environments will result in +deployment issues. Make sure to provide distinct tokens for each environment. + +- Account access: +If you do not have access to the Vercel accounts for staging or production, +please contact your project lead or admin to request access before running +this setup. + +## Get Started + +To add a new vercel configuration, use the following Devmy CLI command: + +```bash copy +devmy generate addon vercel +``` + +## Manual configuration + +in case you want to manually configure the vercel configuration you will have to insert the vercel.json file into +your application. +see the [official documentation](https://vercel.com/docs/projects/project-configuration). +this is a sample `vercel.json` which is usually applied by this addon: + +```json copy +{ + "version": 2, + "regions": ["cdg1"], + "framework": "angular", + "installCommand": "echo \"Install (SKIPPED): pnpm deploy bundles local libraries into node_modules. Running pnpm install again would overwrite them.\"", + "buildCommand": "pnpm build", + "outputDirectory": "dist" +} +``` + +### Environment + +Once you have defined the `vercel.json` file you will need to include the following variables in .env.vault production +and staging areas: + +```dotenv +[APPLICATION_PREFIX]_VERCEL_PROJECT_ID=[application project id] +[APPLICATION_PREFIX]_VERCEL_ORG_ID=[application organization id] +[APPLICATION_PREFIX]_VERCEL_TOKEN=[application vercel token] +``` +To get `VERCEL_PROJECT_ID` and `VERCEL_ORG_ID` you will have to manually link the project to vercel using the vercel +CLI command [vercel link](https://vercel.com/docs/cli/link) command and retrieving them from the `./.vercel/project.json` +file. The operation must be repeated for the staging environment and for the production environment. + +To get the vercel token, you will have to manually generate it at https://vercel.com/account/tokens +(make sure you are logged in to the right account). + +### Pipelines + +#### Gitlab + +Once you have defined the `vercel.json` file you will need to include the `vercel.yml` file in your `.gitlab-ci.yml` + +```yaml copy + +include: + - file: /gitlab-ci/common.yml + project: pillar-1/devops + ref: v1.1.6 + - file: /gitlab-ci/vercel.yml + project: pillar-1/devops + ref: v1.1.6 +``` + +and configure staging and production jobs. to do this, simply create jobs that inherit from `.deploy-vercel` and +`.deploy-staging` if you are configuring the staging environment or `.deploy-production` if you are configuring +production. + +here is an example: + +```yaml copy +"[STAGING] My App": + extends: + - .deploy-staging + - .deploy-vercel + variables: + APPLICATION_PREFIX: MY_APP + APPLICATION_NAME: my-app + +"[PRODUCTION] My App": + extends: + - .deploy-production + - .deploy-vercel + variables: + APPLICATION_PREFIX: MY_APP + APPLICATION_NAME: my-app +``` + +**Pay attention**: `APPLICATION_PREFIX` refers to the prefix used by dotenv-vault for its variables, +while `APPLICATION_NAME` corresponds to the application name specified in its package.json diff --git a/doc/pages/commands/generate/application/angular.mdx b/doc/pages/commands/generate/application/angular.mdx index b0a785d..3afbe58 100644 --- a/doc/pages/commands/generate/application/angular.mdx +++ b/doc/pages/commands/generate/application/angular.mdx @@ -128,6 +128,12 @@ document.startViewTransition. ### TailwindCSS -Both during the creation phase of the Angular application and afterwards, it will be possible to add [TailwindCSS](https://tailwindcss.com/). +Both during the creation phase of the Angular application and afterwards, it will be possible to add [TailwindCSS](/commands/generate/addon/angular_tailwind). The addon will take care of installing the necessary dependencies and initializing the library so that it is ready to use immediately. + +### Vercel + +Both during the creation phase of the Angular application and afterwards, it will be possible to add [Vercel](/commands/generate/addon/vercel) deploy configuration. + +The addon will take care of installing the necessary dependencies and initializing the CDCI so that it is ready to use immediately. diff --git a/doc/pages/commands/generate/application/firebase.mdx b/doc/pages/commands/generate/application/firebase.mdx index 2c2453a..9408587 100644 --- a/doc/pages/commands/generate/application/firebase.mdx +++ b/doc/pages/commands/generate/application/firebase.mdx @@ -1,4 +1,4 @@ -import { Callout } from "nextra/components"; +import {Callout} from "nextra/components"; # Firebase @@ -29,8 +29,8 @@ Subsequently, you will be prompted to configure the development, staging, and pr scanned projects or choose to skip the configuration for now. - If you skip the configuration, you will need to manually set up the - environments in the `.firebaserc` file. + If you skip the configuration, you will need to manually set up the + environments in the `.firebaserc` file. ### Vitest @@ -60,9 +60,9 @@ care. When starting the application in development mode, the `data` folder will be imported automatically. - It is crucial to be careful when modifying data imported and exported on - Firestore, as some end-to-end (E2E) tests may depend on that data and thus - fail. + It is crucial to be careful when modifying data imported and exported on + Firestore, as some end-to-end (E2E) tests may depend on that data and thus + fail. ## Functions @@ -93,11 +93,11 @@ In Firebase Cloud Functions, `onCall` and `onRequest` are two different ways to - **Example Use Case**: Building a custom REST API endpoint or handling webhook requests. - The brick includes wrappers to facilitate development for both types of - Firebase Cloud Functions, `onCall` and `onRequest`. However, `onCall` - functions are **preferred** due to their seamless integration with Firebase - client apps, offering automatic data handling and authentication context, - which simplifies development and enhances security. + The brick includes wrappers to facilitate development for both types of + Firebase Cloud Functions, `onCall` and `onRequest`. However, `onCall` + functions are **preferred** due to their seamless integration with Firebase + client apps, offering automatic data handling and authentication context, + which simplifies development and enhances security. ### Usage @@ -223,3 +223,12 @@ describe("Cats OnCall", () => { }); }); ``` + +## Addons + +### firebase/hosting + +Both during the creation phase of the firebase application and afterwards, it will be possible to add +[hosting](/commands/generate/addon/firebase_hosting) configuration. + +The addon will take care of installing the necessary dependencies and configurations so that it is ready to use immediately. diff --git a/doc/pages/commands/generate/application/next.mdx b/doc/pages/commands/generate/application/next.mdx index aef5313..1e38121 100644 --- a/doc/pages/commands/generate/application/next.mdx +++ b/doc/pages/commands/generate/application/next.mdx @@ -3,3 +3,11 @@ import Wip from '@/components/Wip.tsx'; # Next + +## Addons + +### Vercel + +Both during the creation phase of the Next application and afterwards, it will be possible to add [Vercel](/commands/generate/addon/vercel) deploy configuration. + +The addon will take care of installing the necessary dependencies and initializing the CDCI so that it is ready to use immediately. diff --git a/doc/pages/commands/scaffold.mdx b/doc/pages/commands/scaffold.mdx index a29b7e4..bec78ad 100644 --- a/doc/pages/commands/scaffold.mdx +++ b/doc/pages/commands/scaffold.mdx @@ -53,3 +53,10 @@ of the project. ### Husky We have also configured [Husky](https://typicode.github.io/husky/) for commit linting. + +### Addons + +#### Gitlab +Both during the creation phase of the scaffold and afterwards, it will be possible to add [Gitlab](/commands/generate/addon/gitlab). + +The addon will take care of installing the necessary dependencies and initializing the library so that it is ready to use immediately. diff --git a/doc/pages/get-started.mdx b/doc/pages/get-started.mdx index 29af060..075f7ed 100644 --- a/doc/pages/get-started.mdx +++ b/doc/pages/get-started.mdx @@ -15,8 +15,9 @@ pnpm run dev ### Commands -| Command | Description | alias | -| -------- | ------- | ----- | -| new | Create an NX monorepo to scaffold the project | n | -| generate | Generate a new component such as Applications, Add-ons, Libraries | g | -| --help | Prints information about the command | -h | +| Command | Description | alias | +|----------|-------------------------------------------------------------------|-------| +| new | Create an NX monorepo to scaffold the project | n | +| generate | Generate a new component such as Applications, Add-ons, Libraries | g | +| docs | Open the documentation website | | +| --help | Prints information about the command | -h | diff --git a/lib/src/commands/command_runner_factory.dart b/lib/src/commands/command_runner_factory.dart index ce32c96..4227df5 100644 --- a/lib/src/commands/command_runner_factory.dart +++ b/lib/src/commands/command_runner_factory.dart @@ -1,6 +1,7 @@ import 'package:args/command_runner.dart'; import 'package:chalkdart/chalkstrings.dart'; import 'package:devmy_cli/src/commands/brick_command.dart'; +import 'package:devmy_cli/src/commands/docs_command.dart'; import 'package:devmy_cli/src/commands/node_command.dart'; import 'package:devmy_cli/src/models/models.dart'; @@ -12,24 +13,27 @@ class CommandRunnerFactory { suggestionDistanceLimit: 3, ); - commandRunner.addCommand( - BrickCommand( - brickCommand: configuration.new$, - addons: configuration.addons, - ), - ); - commandRunner.addCommand(NodeCommand( - name: 'utilities', - description: 'Devmy cli Utilities', - children: configuration.utilities - .map((utility) => - BrickCommand(brickCommand: utility, addons: configuration.addons)) - .toList(), - )); - - commandRunner.addCommand(_createGenerateSection(configuration)); - - return commandRunner; + return commandRunner + ..addCommand(DocsCommand()) + ..addCommand( + BrickCommand( + brickCommand: configuration.new$, + addons: configuration.addons, + ), + ) + ..addCommand(NodeCommand( + name: 'utilities', + description: 'Devmy cli Utilities', + children: configuration.utilities + .map( + (utility) => BrickCommand( + brickCommand: utility, + addons: configuration.addons, + ), + ) + .toList(), + )) + ..addCommand(_createGenerateSection(configuration)); } Command _createGenerateSection(CliConfiguration configuration) { diff --git a/lib/src/commands/docs_command.dart b/lib/src/commands/docs_command.dart new file mode 100644 index 0000000..be3eb48 --- /dev/null +++ b/lib/src/commands/docs_command.dart @@ -0,0 +1,29 @@ +import 'dart:async'; +import 'dart:io'; + +import 'package:args/command_runner.dart'; + +class DocsCommand extends Command { + @override + String get description => 'Open official devmy documentation site'; + + @override + String get name => 'docs'; + + @override + FutureOr run() { + _openUrl('https://clidocs-devmy-pillars-projects.vercel.app'); + } + + void _openUrl(String url) { + if (Platform.isWindows) { + Process.run('start', [url], runInShell: true); + } else if (Platform.isMacOS) { + Process.run('open', [url]); + } else if (Platform.isLinux) { + Process.run('xdg-open', [url]); + } else { + print('Unsupported platform'); + } + } +}