DEV Community: Nurlan TL

GitHub Newbie - First repo roadmap (Nuxt 3)

Nurlan TL — Sat, 30 Mar 2024 18:32:23 +0000

Sample workflow to create Nuxt 3 project and its repository on GitHub and listing necessary git operations to start working in a git way.

Prerequisites: GitHub account, git installed locally, terminal, VSCode

Preparation

Create repository My-repo on GitHub.com. This will create new repository with README.md file and if necessary LICENSE file inside.

Open terminal and cd to the folder containing your projects, for example My-projects folder.

cd My-projects

Clone remote repository to local machine using the web URL. Get this url on repositories GitHub page (code/local/HTTPS). It looks like https://github.com/MyName/My-repo.git. Go to local terminal and:

git clone https://github.com/MyName/My-repo.git

This will create My-repo folder inside My-projects folder.

Next initialize our Nuxt 3 (or any other framework) you want:

npx nuxi@latest init My-repo --force

--force option is to use existing folder.

Don't forget to refuse initializing repository as we already done that.

✔ Initialize git repository?
No

Initializing Nuxt 3 creates all necessary files for default Nuxt project. Also Nuxt changes README.md file, and makes no changes to LICENSE file if it exists.

Perfect time to open this My-repo folder in VSCode.

Open VSCode integrated terminal. All commands to be run in my-projects/My-repo folder.

Now we have Remote Repository: The remote repository is the repository hosted on the Git server (e.g., GitHub). When you create a repository on the server, it becomes the remote repository. This repository contains the entire history of the project and serves as the central repository that multiple developers can collaborate on.

And we have Local Repository: The local repository is the copy of the repository that resides on your local machine. When you clone a repository from the remote server, Git creates a local copy of the entire repository, including all branches, commits, and files. This local repository is where you do your work and make changes to the project.

There is also .gitignore file which specifies intentionally untracked files that Git should ignore. This allows you to avoid cluttering your repository with files that are generated during the development process, such as compiled binaries, log files, and dependencies.

We done with preparation steps.

Git starting kit

Commands to know:

git status

The git status command is used to display the current state of the repository, including information about tracked and untracked files, changes that have been staged or not staged for commit, and the branch you're currently on.

git branch

Running this command without any additional arguments will list all the local branches in your repository. The currently checked out branch will be indicated with an asterisk (*) next to its name.

git branch -a

This will list both local and remote branches. Remote branches are prefixed with the name of the remote repository (e.g., origin/main, origin/feature-branch).:
* main
remotes/origin/HEAD -> origin/main
remotes/origin/main

git branch --show-current

This command will display the name of the local branch that you are currently on:
main

git remote show origin

This command will display detailed information about the remote repository, including the default branch and its name. If the default branch is "main", then your local "main" branch is indeed the same as the "main" branch on the remote repository:

* remote origin
Fetch URL: https://github.com/MyName/My-repo.git
Push URL: https://github.com/MyName/My-repo.git
HEAD branch: main
Remote branch:
main tracked
Local branch configured for 'git pull':
main merges with remote main
Local ref configured for 'git push':
main pushes to main (fast-forwardable)

Authenticate

To work with remote branch we need to authenticate your GitHub account when attempting to push changes to the remote repository. Simplest way to do it is to create a personal access token in your GitHub account settings and use the token to access GitHub adding it to your existing remote URL.

git remote set-url origin https://TOKEN@github.com/MyName/My-repo.git

This will add TOKEN to your remote repository URL and you can work with GitHub.

Commit and push

Now we need to commit and push our initial Nuxt setup to local repository. First add newly created files to repository:

git add .

Then we commit changes to local repo:

git commit -m "Initiating Nuxt project"

Now our local repository contains all our changes.

git push origin main:main

Thats all initial steps. Now we can see our Nuxt files on GitHab.com. We have one main branch on remote repo and one main branch on local repo.

Branch

It is time to make some changes to the project: clearing sample files and configuring project. We now create branch for our changes.

Before creating a new branch, it's a good idea to ensure that your local "main" branch is up-to-date with the remote "main" branch. You can do this by pulling any changes from the remote repository:

git pull origin main

Next, create a new branch for the task of clearing the initial sample files and configuring. You can do this using the following command:

git checkout -b clear-and-config

Switched to a new branch 'clear-and-config'

Now we can see our status:

git status

On branch clear-and-config
nothing to commit, working tree clean
admin@iMac My-repo % git branch
* clear-and-config
main

And here we can start working with code. As intended we cleared initial files and make configuration changes.

After that:

git add .

git commit -m "Clear initial sample files and configuring"

Then:

git push -u origin clear-and-config

You are pushing the new branch named "clear-and-config" to the remote repository named "origin". This command does not affect the "main" branch on the remote repository.

The -u option, short for --set-upstream, tells Git to set up tracking between the local branch and the remote branch. This means that future git pull and git push commands will automatically know where to pull from and push to without needing to specify the remote and branch explicitly.

New branch "clear-and-config" will be created on the remote repository (if it doesn't already exist) and set up to track the local branch. This means that any future pushes from the local "clear-and-config" branch will be directed to the corresponding branch on the remote repository.

You don't need to create a remote "clear-and-config" branch separately. Git handles the creation of the remote branch for you when you push the local branch for the first time.

Merge or rebase

Once your changes are ready to be integrated into the main branch, you can merge them using git merge or rebase them using git rebase, depending on your preferred workflow and the requirements of your project.

Merge

First, switch to the branch you want to merge changes into. For example, if you want to merge changes into the "main" branch:

git checkout main

Next, merge the changes from the feature branch (in this case, "clear-and-config") into the main branch:

git merge clear-and-config

If Git detects any conflicts between the changes in the two branches, it will pause the merge process and ask you to resolve the conflicts manually. You can use a text editor or a merge tool to resolve conflicts.

Push Changes :

git push origin main

After completing these steps, the changes from your feature branch will be merged into the main branch, and both branches will be up-to-date with each other.

Rebase

Git rebase is another way to integrate changes from one branch into another, similar to merging. However, it operates differently under the hood and can result in a cleaner, more linear history compared to merging.

When you rebase a branch onto another branch, Git takes the entire series of commits from the branch being rebased and "replays" them on top of the target branch. This essentially rewrites the commit history of the rebased branch, making it appear as if the changes were made directly on top of the target branch.

Switch to the branch you want to rebase. For example, if you want to rebase the "clear-and-config" branch onto the "main" branch:

git checkout clear-and-config

Rebase onto the Target Branch:
Next, rebase the current branch onto the target branch (e.g., "main"):

bash

git rebase main

Resolve any Rebase Conflicts (if necessary):
Similar to merging, if Git encounters any conflicts during the rebase process, it will pause and ask you to resolve them manually.

Continue the Rebase:

git rebase --continue

After resolving conflicts, you can continue the rebase by using git rebase --continue. If you encounter any conflicts during the rebase, you'll need to resolve them and continue the process until all commits have been replayed.

The rebase operation modifies the commit history of the clear-and-config branch locally. It takes the commits from the clear-and-config branch and replays them on top of the main branch, essentially rewriting the commit history of the clear-and-config branch.

The main branch on your local machine remains unchanged during the rebase operation. The changes from the clear-and-config branch are applied on top of the main branch, but the main branch itself does not undergo any direct modifications.

After completing the rebase locally and resolving any conflicts, you push the changes from the clear-and-config branch to the remote repository. This updates the clear-and-config branch on the remote repository with the rebased commits, effectively incorporating them into the commit history of the main branch on the remote repository.

In summary, the rebase operation affects the commit history of the clear-and-config branch locally, while the main branch remains unaffected until you push the changes to the remote repository.

git push origin clear-and-config --force

This command will update the remote clear-and-config branch with the rebased commits, incorporating them into the commit history of the main branch on the remote repository.

It's important to use the --force option when pushing after a rebase to overwrite the existing history of the remote branch with the rewritten history resulting from the rebase. However, use force-push with caution, especially if others are working with the same branch, as it can cause confusion and potentially overwrite their work.

Final

That is it. It is very simplified workflow for single developer who don't change main until feature branch is done and merged into main. For complex scenarios read more. Good luck.

Tips to create Web components using Vue 3, TS, Vite.

Nurlan TL — Sat, 10 Dec 2022 19:48:26 +0000

Recently I had a task to create a Web Component. My favorite framework is Vue 3 and I had no intentions to use another. At first glance there are a lot of videos and articles how to do it but some of them use slightly different stack and others give only part of info I needed. Finally I managed to do it and now want to share my experience.

Install Vite with Vue latest and TS support.

Create Vue SFC component to be your web component, its name should have ce.vue extension:

SampleSimple.ce.vue

We can use it inside our App.vue as any other components. And it will help us to test and debug it on developer server:

npm run dev

You implement the logic you want inside this SampleSimple.ce.vue and place any other components inside. You don't need to name child components with ce.vue extension, just usual vue extension.

Lets move to creating final web component from you vue component. First of all we need to create second main.ts file whose job is to generate final web components js file. As you can imagine its name will be:

main.ce.ts

import { defineCustomElement } from 'vue'
import SimpleSampleComponent from './SimpleSample.ce.vue'

const SimpleSample = defineCustomElement(SimpleSampleComponent)

customElements.define('simple-sample', SimpleSample)

Our script part of package.json needs no changes:

  "scripts": {
    "dev": "vite",
    "build": "vue-tsc --noEmit && vite build",
    "preview": "vite preview"
  }

The most important part is vite.config.ts:

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag.includes('simple-sample')
        }
      }
    })
  ],
  build: {
    lib: {
      entry: './src/main.ce.ts',
      name: 'simple-sample',
      // the proper extensions will be added
      fileName: 'simple-sample'
    }
  },
  define: {
    'process.env': process.env
  }
})

We have changed build part, added define for process.env, and added vue compilerOptions isCustomElement to distinguish our custom element.

Thats all. Now run:

npm run build

and that will put simple-sample.js and simple-sample.umd.cjs files into dist folder.

To use our new web component you can put simple-sample.js to any place you want. Then add

<script src="path/to/simple-sample.js"></script>

to html header and use your component like that:

<simple-sample></simple-sample>

If you defined properties inside your SimpleSample.ce.vue you add properties too:

<simple-sample property1="value"></simple-sample>

What about styles? Styles that are inside SimpleSample.se.vue are included into resulting web component:

<script setup lang="ts">
...
</script>
<template>
  ...
</template>
<style>
// our web component styles
</style>

If you import styles inside script part of the component they will be ignored by Vite build process. So the only place is styles part of SFC. Thats ok if your styles are small but if there are a lot of lines it is not comfortable to work with. So there is a solution - scss. We can use scss import and move styles to another directory and organize them in more smart manner:

<script setup lang="ts">
...
</script>
<template>
  ...
</template>
<style lang="scss">
@import '../scss/file1';
@import '../scss/file2';
@import '../scss/file3';
</style>

Thats all. I hope this info will be helpfull.