It was a romantic idea. Eviva l'arte! and all that.

But I'm shutting it down. The website at frodigo.com will no longer be available, and the project won't be continued. Website content will be available on https://github.com/RetroModernDev/garage.

Why?

Because my resistance was pointless.

Big tech companies have already decided for all of us. AI is not a direction for the future. It's the present. Fighting it felt like standing in front of a train and asking it to slow down. The train doesn't care.

I still believe that understanding code matters. I still think that writing your first function yourself teaches you something that no AI-generated output ever will. But spending energy on resistance? That's a losing game. I'd rather spend that energy on creating things.

What I'm doing now

I shifted my focus. Instead of fighting AI, I have put my energy into these things:

• Restoring old computers — I'm into retro hardware, especially Commodore Amiga. Recapping, repainting cases, bringing old machines back to life.
• Playing games — retro and modern. Rediscovering what made me fall in love with computers in the first place.
• Creating games and apps with AI — instead of resisting the technology, I use it to make things. That feels much better than complaining.

Where to find me

I started a new brand called RetroModern.dev — where retro meets modern. Also I changed my nickname everywhere from Frodigo to RetroModernDev. Yeah, I have started a new digital life. :)

• YouTube: https://www.youtube.com/@RetroModernDev
• Website: https://retromodern.dev/
• Medium (English): https://medium.com/@RetroModernDev

The YouTube channel and website are in Polish, but let's be honest — with today's translation tools, that's not really a barrier anymore.

You can also find me on https://x.com/RetroModernDev · https://instagram.com/retromoderndev · https://www.tiktok.com/@retromoderndev · https://www.facebook.com/retromoderndev/

RSS

If you followed the Garage via RSS, here are the new feeds:

• Website: https://retromodern.dev/feed/
• Medium: https://medium.com/feed/@RetroModernDev

Good bye

The Garage was a good idea at a wrong time. Or maybe at the right time — it helped me realize that resisting tools is not the same as preserving craft. You can use AI and still care about quality. You can vibe code and still understand what's happening under the hood.

I just don't want to spend my time configuring rebellion anymore. I'd rather restore an Amiga 600 and make a video about it.

See you on the other side. Bye!

Guess what? I have felt mental pain because I needed to write this code. After a few hours, I was exhausted. Is this me? Am I the same person who some time ago could write code for hours in hyperfocus?

I have unlearned how to solve problems without any help. Am I junior again? Perhaps it’s just me, because when I open LinkedIn, I see how much AI helps, and how people are happier when they use AI tools.

Or maybe people like me are silent because it’s a shame to talk about failures in this successful world? Or perhaps they are quiet because they assume that showing scepticism about AI will create a problem in their current job or hinder their ability to find a new one.

AI doesn’t need to be smarter than us to be dangerous. It just needs to make us dumber. As we increasingly outsource our thinking to machines, the ability to solve problems with our hands and brains is becoming a rare skill.

The illusion of progress

People commonly say that the main advantage of using AI is to make things faster. But is it the case for all problems? Do all companies work in an ASAP culture? Is it really developing things with AI faster?

When I started writing code in C#, I used Cursor a lot, because I had a skill issue. I was familiar with general programming principles, and I had written code in a few other languages. But I didn’t know C#. Using AI was magical because I felt that I was more capable than I actually was.

Also, at the beginning of my C# career, I worked on relatively simple tasks that didn’t require advanced .NET/C # skills. After six months, I started feeling frustrated with using Cursor because, in the meantime, I had learned C# a little bit, and things that Cursor did for me started to look less magical than before.

I realized that the code produced by the Cursor is a mess. Additionally, I began working on problems that the Cursor was unable to solve. So, I needed to solve problems by hand, but wait - it wasn't as easy as I thought. After months of using Cursor, writing code started to be painful. Being focused was aching even more.

The skills we’re losing

AI can help us with many things, such as writing, problem-solving, finding information, memorizing, and… thinking. But should we put thinking into AI?

I am confident we shouldn’t, mainly because AI is not capable of thinking. It just produces words. However, it appears to be thinking. This is another illusion that many people buy as fact.

AI helps with current problems, but it can also create a long-term dependence. Take a look:

• When you use Grammarly, you will not learn grammar
• When you use Google Maps, you will not be able to travel anywhere without this app and GPS.
• When you ask AI about a solution to each problem, you will not be able to solve the problems by yourself.

A person without critical thinking skills becomes as stupid as these language models.

The counterargument

You can respond that “AI is just a tool — it’s up to us to use it responsibly,” but this isn’t enough, because using AI is addictive.

As I pointed out before, especially when you do not have the skills for something, help from AI looks like a magical thing. Then you are more and more addicted, and don’t see that you fall into the trap of getting rid of your basic skills.

Theoretically, you can feel that you learn when you use AI, but when you do a real test: disable internet connection, disable AI, have only a problem and a sheet of paper. Then you see a real problem. Then you see, oh, I can’t even start. Where is my AI friend, oh gosh!

You thought you learned a lot and gained new skills thanks to AI, but in reality, you learned almost nothing and lost some of your existing skills. Thanks, AI!

Reclaiming our skills

I have experienced all of this that I described in my life and work. I used Cursor for everything at the job, and I even used AI to write my journal. I stopped blogging because I couldn’t find the motivation to write an article on my own.

But the human brain is remarkably capable of learning and adapting throughout life. We can reclaim our independence by consciously training our skills.

You can achieve independence by learning. You can still use AI, but you can also practice skills without AI assistance. You can try first, solve the problem by yourself, and ask AI for help after a few tries.

If you’re unsure where to start, I recommend installing NeoVim. I did this, and I have many problems to solve, many opportunities to learn new things, and a lot of fun!

Conclusion

Artificial intelligence is supposed to improve our quality of life and work, but the hidden cost is that we become dependent and subservient to machines and the corporations that produce them. We’ve outsourced so much thinking that we risk becoming consumers, rather than creators of knowledge. When we use AI, we need to consider whether we are using AI or if AI is actually using us.

Published: 12/09/2025 #blog #AIImpact #FutureOfWork #AISkills #programming #CursorAI #digitalwellbeing

Life as a developer

When I worked as a programmer, I had everything under control. I could find a solution to almost every problem. I felt like an expert in my field.

I'd never been a project/team leader, so the offer from VueStorefront was quite interesting at the time.

I would have continued coding Magento, but a 30% raise and the move from a software house to a product company also prompted me to make a change.

Team leading

In the first weeks, I felt like I was wearing someone else's shoes. The skills that made me an effective programmer—deep focus, technical perfectionism, and independent work—were no longer enough.

I painfully recognized all my weaknesses. I tried to figure it out, caught up, and worked my ass off. Every day was incredibly intense.

For a long time, I tried to fit into the image of the "ideal Tech Lead." It wasn't until I stopped pretending and started drawing from my own experiences that I found my authentic voice.

You can read books and learn how to be a perfect manager. But honesty is what matters to people. It's better to be yourself and often even admit a mistake or weakness than to pretend to be someone you're not.

I received praise; they said I was doing well and that I was a good leader, but I felt increasingly overwhelmed.

The turning point came when I realized I had started to fear the sight of my computer. The same work that once energized me now left me exhausted and disconnected.

More hours at work === better results. Reality quickly verified this belief. When I was exhausted, I made worse decisions and couldn't support the team.

In meetings, I caught myself nodding while my mind wandered elsewhere. At home, I couldn't stop thinking about work, and at work, I couldn't focus on tasks.

That's enough

I needed help. After months of trying to be the perfect technical leader who could do everything, I finally opened up to my boss about my struggles.

After that, I started setting clear boundaries between work time and private time, treating my energy as a limited resource that needed to be carefully managed.

I tried a lot to recover, but finally, after three years, I decided that I needed to step back and stop being a team lead. Anyway, I learned a great deal, and it was worth the time and energy I invested.

Final word

I spent too long trying to be a tech lead, instead of simply being myself. The most valuable lesson I learned wasn't about management techniques or project planning.

Actually, it was about the power of authenticity. A team leader doesn't have to be the same as all other managers. The goal is to build a team around your strengths and be honest about your weaknesses.

Published: 12/09/2025 #blog #leadership

Note: You can find https://github.com/Frodigo/garage/blob/main/Atlas/Engineering/machine-learning/level-0-python-and-math-essentials/numpy/numpy-essentials.ipynb (On blog you can see this notebook converted to text).

NumPy (Numerical Python) is a Python library that makes working with numbers faster and easier. It offers new datatype: ndarray, vectorization and bunch of useful functions. NumPy is a tool that every ML or Data Engineer use daily.In this Notebook, I am going through NumPy features and show examples how it can be used.

Installation

Run a cell below to install numpy:

%pip install numpy

Requirement already satisfied: numpy in /opt/anaconda3/envs/mlenv/lib/python3.13/site-packages (2.2.2)
Note: you may need to restart the kernel to use updated packages.

Run this code to verify NumPy is installed:

import numpy as np
print(np.__version__)

2.2.2

You should see a version of NumPy.

What this means:

• import numpy - Load the NumPy library so you can use it
• as np - Create a nickname "np" so you can type np.array() instead of numpy.array() every time (we are lazy and we prefer to write to letters instead of five, yeah?)
• This is a convention - most NumPy code uses np, so you'll see it everywhere

Why not just import numpy? You can! But np is shorter and everyone uses it, so your code will match examples you find online. (and as i said, we are lazy, or at least me).

NumPy Advantages

Once NumPy is installed, let's see it biggest advantages. Vectorization allows you to apply an operation to each element in array without doing a loop. Another thing is a bunch of methods that allows you to do mathematical operations. All of this will not be possible without a ndarray, which is a core data structure in NumPy.

Vectorization

Vectorization allows applying an operation to an entire array at once, rather than looping through each element.

In NumPy, you can perform operations on entire arrays without explicit loops. For example arr + 10 will add 10 to each element of arr.

Let's see this in action:

import time  # Built-in Python module for measuring time

# Example: Converting engine RPM to different units
# Let's say we have RPM readings from a car's engine
rpm_values = [1000, 2000, 3000, 4000, 5000]

# Method 1: Using Python loop (slow way)
# Convert RPM to radians per second (multiply by 0.10472)
result_python = []
for rpm in rpm_values:
    result_python.append(rpm * 0.10472)
print(f"Using Python loop: {result_python}")

# Method 2: Using NumPy vectorization (fast way)
rpm_array = np.array(rpm_values)  # Convert list to NumPy array
result_numpy = rpm_array * 0.10472  # Single operation on entire array!
print(f"Using NumPy vectorization: {result_numpy}")
print("→ Same result, less code! This is called 'vectorization'")

Using Python loop: [104.72, 209.44, 314.15999999999997, 418.88, 523.6]
Using NumPy vectorization: [104.72 209.44 314.16 418.88 523.6 ]
→ Same result, less code! This is called 'vectorization'

In example above you can see that we can just do rpm_array * 0.10472 and we don't need looping. That's great - less code, same results. But let's see how time consuming are these methods in large datasets. Imagine analyzing RPM data from 1 million readings. Spoiler: NumPy is way more faster!

# Create large dataset: 1 million RPM values from 0 to 7000
# Note: range(1000000) creates numbers 0 to 999,999, then we multiply by 7
python_list = [rpm * 7 for rpm in range(1000000)]  # List comprehension
numpy_array = np.array(python_list)  # Convert to NumPy array

# Time the Python loop method
start = time.time()  # Record start time
result_python = []
for rpm in python_list:
    result_python.append(rpm * 0.10472)  # Convert each RPM
python_time = time.time() - start  # Calculate elapsed time

# Time the NumPy vectorization method
start = time.time()
result_numpy = numpy_array * 0.10472  # Single operation!
numpy_time = time.time() - start

print(f"Python loop time: {python_time:.4f} seconds")
print(f"NumPy vectorized time: {numpy_time:.4f} seconds")
print(f"NumPy is {python_time/numpy_time:.1f}x faster!")

Python loop time: 0.0327 seconds
NumPy vectorized time: 0.0008 seconds
NumPy is 40.7x faster!

40x faster, amazing, no? Let's take a look at other vectorization examples:

# Example: Processing speed data from GPS
speeds_mph = np.array([30, 45, 60, 70, 85])  # Speeds in mph
print(f"Original speeds (mph): {speeds_mph}")

# Convert to km/h (multiply by 1.60934)
speeds_kmh = speeds_mph * 1.60934
print(f"Converted to km/h: {speeds_kmh}")

# Calculate speeds in m/s (divide km/h by 3.6)
speeds_ms = speeds_kmh / 3.6
print(f"Converted to m/s: {speeds_ms}")

# Add 5 mph to all speeds (simulating cruise control adjustment)
adjusted_speeds = speeds_mph + 5
print(f"Adjusted speeds (+5 mph): {adjusted_speeds}")

# Calculate power (simplified: power ≈ speed²)
power = speeds_mph ** 2
print(f"Relative power (speed²): {power}")

Original speeds (mph): [30 45 60 70 85]
Converted to km/h: [ 48.2802  72.4203  96.5604 112.6538 136.7939]
Converted to m/s: [13.41116667 20.11675    26.82233333 31.29272222 37.99830556]
Adjusted speeds (+5 mph): [35 50 65 75 90]
Relative power (speed²): [ 900 2025 3600 4900 7225]

Mathematical Operations

NumPy offers built-in functions for linear algebra, statistics, and more. These are essential for analyzing automotive data - like calculating average fuel consumption, analyzing engine performance, or processing sensor readings.

Let's explore the most useful functions with automotive examples:

# Example: Fuel consumption data (L/100km) from 10 different trips
fuel_consumption = np.array([7.2, 8.5, 6.9, 9.1, 7.8, 8.3, 7.5, 6.7, 8.9, 7.4])
print(f"Fuel consumption data (L/100km): {fuel_consumption}")

Fuel consumption data (L/100km): [7.2 8.5 6.9 9.1 7.8 8.3 7.5 6.7 8.9 7.4]

Statistics

Based on our example we can easily analyze fuel consumption, calculating average speeds, finding performance metrics, or analyzing sensor data.

print(f"Fuel consumption data (L/100km): {fuel_consumption}")
print(f"\nStatistics:")
print(f"Mean (average): {np.mean(fuel_consumption):.2f} L/100km")
print(f"Median (middle value): {np.median(fuel_consumption):.2f} L/100km")
print(f"Standard deviation (variability): {np.std(fuel_consumption):.2f} L/100km")
print(f"Variance: {np.var(fuel_consumption):.2f}")
print(f"Minimum: {np.min(fuel_consumption):.1f} L/100km (best efficiency)")
print(f"Maximum: {np.max(fuel_consumption):.1f} L/100km (worst efficiency)")
print(f"Range: {np.max(fuel_consumption) - np.min(fuel_consumption):.1f} L/100km")
print(f"50th percentile (median): {np.percentile(fuel_consumption, 50):.2f} L/100km")

Fuel consumption data (L/100km): [7.2 8.5 6.9 9.1 7.8 8.3 7.5 6.7 8.9 7.4]

Statistics:
Mean (average): 7.83 L/100km
Median (middle value): 7.65 L/100km
Standard deviation (variability): 0.79 L/100km
Variance: 0.63
Minimum: 6.7 L/100km (best efficiency)
Maximum: 9.1 L/100km (worst efficiency)
Range: 2.4 L/100km
50th percentile (median): 7.65 L/100km

Basic Math Operations

Simple but essential operations for automotive calculations.

# Example: Engine RPM data
rpm = np.array([1000, 2000, 3000, 4000, 5000])
print(f"Engine RPM: {rpm}")

# Absolute value
rpm_diff = np.array([-100, 50, -200, 150, -75])
print(f"RPM differences: {rpm_diff}")
print(f"Absolute differences: {np.abs(rpm_diff)}")

# Square root
power = np.array([100, 200, 300, 400, 500])  # HP
print(f"\nPower (HP): {power}")
print(f"Square root of power: {np.sqrt(power)}")

# Exponentiation
speed = np.array([30, 40, 50, 60, 70])  # mph
print(f"\nSpeed (mph): {speed}")
print(f"Speed squared (used in power calculations): {speed ** 2}")

Engine RPM: [1000 2000 3000 4000 5000]
RPM differences: [-100   50 -200  150  -75]
Absolute differences: [100  50 200 150  75]

Power (HP): [100 200 300 400 500]
Square root of power: [10.         14.14213562 17.32050808 20.         22.36067977]

Speed (mph): [30 40 50 60 70]
Speed squared (used in power calculations): [ 900 1600 2500 3600 4900]

Rounding & Precision

When working with data, you often need to round values for display or calculations.

# Example: Precise fuel consumption readings
fuel_consumption = np.array([7.234, 8.567, 6.891, 9.123, 7.456])
print(f"Precise fuel consumption (L/100km): {fuel_consumption}")

# Round to 2 decimal places (typical for fuel consumption)
rounded = np.round(fuel_consumption, 2)
print(f"Rounded to 2 decimals: {rounded}")

# Round down (floor) - useful for conservative estimates
floored = np.floor(fuel_consumption)
print(f"Floored (rounded down): {floored}")

# Round up (ceiling) - useful for worst-case estimates
ceiled = np.ceil(fuel_consumption)
print(f"Ceiled (rounded up): {ceiled}")

# Example: Speed readings
speed = np.array([45.7, 62.3, 78.9, 91.2])
print(f"\nSpeed readings (mph): {speed}")
print(f"Rounded speeds: {np.round(speed)}")

Precise fuel consumption (L/100km): [7.234 8.567 6.891 9.123 7.456]
Rounded to 2 decimals: [7.23 8.57 6.89 9.12 7.46]
Floored (rounded down): [7. 8. 6. 9. 7.]
Ceiled (rounded up): [ 8.  9.  7. 10.  8.]

Speed readings (mph): [45.7 62.3 78.9 91.2]
Rounded speeds: [46. 62. 79. 91.]

Understanding NumPy Arrays (ndarray)

ndarray is a core data structure in NumPy - a multidimensional array that can hold lots of data efficiently. Think of it as a supercharged Python list that's optimized for math.

Key difference from Python lists:

• Python lists can contain different data types (heterogeneous): [1, "hello", 3.5]
• NumPy arrays must contain the same data type (homogeneous): [1, 2, 3] or [1.0, 2.0, 3.0]

Creating arrays

my_arr = np.array([1, 2, 3, 4, 5])
my_arr.dtype

ones = np.ones((3, 4))
zeros = np.zeros((2, 3, 4))
full = np.full((2, 3), 4)
arange = np.arange(10, 100, 10)
linspace = np.linspace(0, 1, 5)

print(ones)
print(zeros)
print(full)
print(arange)
print(linspace)


random_arr = np.random.randint(0, 10, (3, 4))
print(random_arr)

random_arr_2 = np.random.rand(2, 2, 2, 2)
print(random_arr_2)

[[1. 1. 1. 1.]
 [1. 1. 1. 1.]
 [1. 1. 1. 1.]]
[[[0. 0. 0. 0.]
  [0. 0. 0. 0.]
  [0. 0. 0. 0.]]

 [[0. 0. 0. 0.]
  [0. 0. 0. 0.]
  [0. 0. 0. 0.]]]
[[4 4 4]
 [4 4 4]]
[10 20 30 40 50 60 70 80 90]
[0.   0.25 0.5  0.75 1.  ]
[[6 1 8 4]
 [1 7 3 9]
 [8 3 1 4]]
[[[[0.59130761 0.66421588]
   [0.33191183 0.29026851]]

  [[0.39059243 0.12892054]
   [0.01739604 0.80804896]]]


 [[[0.32469533 0.29820351]
   [0.21903883 0.53010489]]

  [[0.53026239 0.05754576]
   [0.31187082 0.55165342]]]]

Array Properties

Understanding array properties helps you work with your data effectively.

# Example: Engine sensor data
sensor_data = np.array([[30, 2500, 7.2],   # [speed, RPM, fuel]
                        [45, 3000, 8.5],
                        [60, 3500, 9.1]])

print(f"Array:\n{sensor_data}")
print(f"\nArray Properties:")
print(f".shape → {sensor_data.shape} (rows, columns)")
print(f".ndim → {sensor_data.ndim} (number of dimensions)")
print(f".size → {sensor_data.size} (total elements)")
print(f".dtype → {sensor_data.dtype} (data type)")
print(f".itemsize → {sensor_data.itemsize} bytes per element")
print(f".nbytes → {sensor_data.nbytes} bytes total")

# Example: 1D array
speed_data = np.array([30, 45, 60, 70, 85])
print(f"\n1D array: {speed_data}")
print(f"Shape: {speed_data.shape} (note the comma - it's a tuple!)")
print(f"Dimensions: {speed_data.ndim}D")

Array:
[[  30.  2500.     7.2]
 [  45.  3000.     8.5]
 [  60.  3500.     9.1]]

Array Properties:
.shape → (3, 3) (rows, columns)
.ndim → 2 (number of dimensions)
.size → 9 (total elements)
.dtype → float64 (data type)
.itemsize → 8 bytes per element
.nbytes → 72 bytes total

1D array: [30 45 60 70 85]
Shape: (5,) (note the comma - it's a tuple!)
Dimensions: 1D

Array properties help you understand your data. .shape shows the structure of the array and it's helpful to check if the data format is correct. .dtype indicates what type of data is stored in the array. .nbytes displays how much memory the array uses (critical when working with very large arrays).

ndarray (n-dimensional array)

ndarray is multidimensional array that can be 0D (scalar), 1D (vector), 2D (matrix), or higher dimensions. Let's take a look at examples.

0D Array (scalar)

scalar = np.array(42)
print(f"Array: {scalar}")
print(f"Shape: {scalar.shape}")
print(f"Dimensions: {scalar.ndim}D")
print(f"Data type: {scalar.dtype}")
print(f"Size: {scalar.size}")

Array: 42
Shape: ()
Dimensions: 0D
Data type: int64
Size: 1

1D array (vector)

vector = np.array([1, 2, 3, 4, 5])
print(f"Array: {vector}")
print(f"Shape: {vector.shape}")
print(f"Dimensions: {vector.ndim}D")
print(f"Data type: {vector.dtype}")
print(f"Size: {vector.size}")

Array: [1 2 3 4 5]
Shape: (5,)
Dimensions: 1D
Data type: int64
Size: 5

2D array (matrix)

matrix = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
print(f"Array:\n{matrix}")
print(f"Shape: {matrix.shape} (rows, columns)")
print(f"Dimensions: {matrix.ndim}D")
print(f"Data type: {matrix.dtype}")
print(f"Size: {matrix.size} (total elements)")

Array:
[[1 2 3]
 [4 5 6]
 [7 8 9]]
Shape: (3, 3) (rows, columns)
Dimensions: 2D
Data type: int64
Size: 9 (total elements)

3D array

array_3d = np.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])
print(f"Array:\n{array_3d}")
print(f"Shape: {array_3d.shape} (depth, rows, columns)")
print(f"Dimensions: {array_3d.ndim}D")
print(f"Data type: {array_3d.dtype}")
print(f"Size: {array_3d.size} (total elements)")

Array:
[[[1 2]
  [3 4]]

 [[5 6]
  [7 8]]]
Shape: (2, 2, 2) (depth, rows, columns)
Dimensions: 3D
Data type: int64
Size: 8 (total elements)

Creating array from list

list_1d = [1, 2, 3, 4, 5]
list_2d = [[1, 2, 3], [4, 5, 6]]
arr_from_list_1d = np.array(list_1d)
arr_from_list_2d = np.array(list_2d)
print(f"1D list {list_1d} → Array: {arr_from_list_1d}")
print(f"2D list {list_2d} → Array:\n{arr_from_list_2d}")

1D list [1, 2, 3, 4, 5] → Array: [1 2 3 4 5]
2D list [[1, 2, 3], [4, 5, 6]] → Array:
[[1 2 3]
 [4 5 6]]

Homogenous data type

ndarray stores the same data type. If needed types will be converted.

mixed_list = [1, 2, 3.5, 4]  # Mix of int and float
homogeneous_array = np.array(mixed_list)
print(f"Mixed list: {mixed_list}")
print(f"NumPy array: {homogeneous_array}")
print(f"Data type: {homogeneous_array.dtype} (all converted to float)")

Mixed list: [1, 2, 3.5, 4]
NumPy array: [1.  2.  3.5 4. ]
Data type: float64 (all converted to float)

Broadcasting

What is broadcasting? NumPy allows using arrays of different shapes in arithmetic operations thanks to broadcasting rules, which automatically handle shape mismatches. Broadcasting is a powerful mechanism that lets NumPy work with arrays of different shapes when performing operations, making code more concise and readable.

Let's see this in action with automotive examples:

Example 1: Adding a calibration offset to all speed readings

import numpy as np

# Speed readings from GPS (mph) - 2D array with multiple trips
speeds = np.array([[30, 45, 60],
                   [40, 55, 70],
                   [35, 50, 65]])

# Calibration offset: GPS is reading 2 mph too low
calibration_offset = 2

print(f"Speed readings (mph):\n{speeds}")
print(f"\nCalibration offset: +{calibration_offset} mph")
print(f"\nAdjusted speeds:\n{speeds + calibration_offset}")
print("→ The scalar (2) is 'broadcast' to every element!")

Speed readings (mph):
[[30 45 60]
 [40 55 70]
 [35 50 65]]

Calibration offset: +2 mph

Adjusted speeds:
[[32 47 62]
 [42 57 72]
 [37 52 67]]
→ The scalar (2) is 'broadcast' to every element!

Example 2: Applying different adjustments per column

speeds = np.array([[30, 45, 60],
                   [40, 55, 70],
                   [35, 50, 65]])

# Different calibration offsets
trip_adjustments = np.array([2, 3, 1])

print(f"Speed readings (mph):\n{speeds}")
print(f"\nTrip adjustments: {trip_adjustments}")
print(f"\nAdjusted speeds:\n{speeds + trip_adjustments}")

Speed readings (mph):
[[30 45 60]
 [40 55 70]
 [35 50 65]]

Trip adjustments: [2 3 1]

Adjusted speeds:
[[32 48 61]
 [42 58 71]
 [37 53 66]]

Example 3: Applying adjustments per row

speeds = np.array([[30, 45, 60],
                   [40, 55, 70]])

time_adjustments = np.array([[1],
                             [2]])

print(f"Speed readings (mph):\n{speeds}")
print(f"\nTime-based adjustments (column vector):\n{time_adjustments}")
print(f"\nAdjusted speeds:\n{speeds + time_adjustments}")

Speed readings (mph):
[[30 45 60]
 [40 55 70]]

Time-based adjustments (column vector):
[[1]
 [2]]

Adjusted speeds:
[[31 46 61]
 [42 57 72]]

Random Number Generation

NumPy provides functions for generating random numbers, probability distributions, and random sampling.

# Simulate random speed readings (mph)
speeds = np.random.randint(30, 90, size=10)  # Random speeds between 30-90 mph
print(f"Random speeds (mph): {speeds}")

Random speeds (mph): [53 82 65 69 53 32 51 82 31 53]

# Simulate speed readings with realistic distribution
realistic_speeds = np.random.normal(loc=60, scale=15, size=10)  # Mean 60, std 15
print(f"\nRealistic speeds (normal distribution): {realistic_speeds}")
print(f"Mean: {realistic_speeds.mean():.1f} mph, Std: {realistic_speeds.std():.1f} mph")

Realistic speeds (normal distribution): [52.95788421 68.13840065 53.04873461 53.0140537  63.62943407 31.30079633
 34.12623251 51.56568706 44.80753319 64.71370999]
Mean: 51.7 mph, Std: 11.7 mph

# Simulate fuel consumption (L/100km) - uniform distribution
fuel_consumption = np.random.uniform(low=6.0, high=10.0, size=5)
print(f"Simulated fuel consumption (L/100km): {fuel_consumption}")
print(f"Average: {fuel_consumption.mean():.2f} L/100km")

Simulated fuel consumption (L/100km): [7.16857859 7.46544737 7.82427994 9.14070385 6.79869513]
Average: 7.68 L/100km

# Simulate RPM readings (1000-7000 RPM)
rpm_readings = np.random.randint(1000, 7000, size=5)
print(f"Random RPM readings: {rpm_readings}")

Random RPM readings: [6390 6226 6191 4772 4092]

# Simulate RPM with normal distribution (typical cruising RPM)
cruising_rpm = np.random.normal(loc=2500, scale=500, size=5)
print(f"\nCruising RPM (normal distribution): {cruising_rpm}")
print(f"Mean: {cruising_rpm.mean():.0f} RPM")

Cruising RPM (normal distribution): [2382.92331264 2382.93152153 3289.60640775 2883.71736458 2265.26280703]
Mean: 2641 RPM

# Simulate selecting random trips for analysis
trip_ids = ['Trip 1', 'Trip 2', 'Trip 3', 'Trip 4', 'Trip 5']
selected_trips = np.random.choice(trip_ids, size=3, replace=False)
print(f"Available trips: {trip_ids}")
print(f"Randomly selected trips: {selected_trips}")

Available trips: ['Trip 1', 'Trip 2', 'Trip 3', 'Trip 4', 'Trip 5']
Randomly selected trips: ['Trip 3' 'Trip 2' 'Trip 5']

print("Setting seed ensures reproducible results (important for testing!):")
np.random.seed(42)
speed1 = np.random.randint(30, 90, size=3)
print(f"With seed(42): {speed1}")

np.random.seed(42)
speed2 = np.random.randint(30, 90, size=3)
print(f"With seed(42) again: {speed2}")
print("→ Same seed produces same random numbers!")

Setting seed ensures reproducible results (important for testing!):
With seed(42): [68 81 58]
With seed(42) again: [68 81 58]
→ Same seed produces same random numbers!

Common Mistakes

Here are some common mistakes beginners make when starting with NumPy:

Mistake 1: Forgetting to convert to NumPy array

my_list = [10, 20, 30]
print(f"Python list: {my_list}")
print(f"my_list * 2 → {my_list * 2}")  # Duplicates the list!
print("⚠️ Python lists multiply by duplicating, not by element!")

my_array = np.array([10, 20, 30])
print(f"\nNumPy array: {my_array}")
print(f"my_array * 2 → {my_array * 2}")  # Multiplies each element!
print("✅ NumPy arrays multiply each element")

Python list: [10, 20, 30]
my_list * 2 → [10, 20, 30, 10, 20, 30]
⚠️ Python lists multiply by duplicating, not by element!

NumPy array: [10 20 30]
my_array * 2 → [20 40 60]
✅ NumPy arrays multiply each element

Mistake 2: Mixing up array dimensions

# 1D array (like a row of data)
array_1d = np.array([10, 20, 30])
print(f"1D array: {array_1d}")
print(f"Shape: {array_1d.shape}")

# 2D array with 1 row
array_2d_row = np.array([[10, 20, 30]])
print(f"\n2D array with 1 row: {array_2d_row}")
print(f"Shape: {array_2d_row.shape}")

# 2D array with 1 column
array_2d_col = np.array([[10], [20], [30]])
print(f"\n2D array with 1 column:\n{array_2d_col}")
print(f"Shape: {array_2d_col.shape}")

1D array: [10 20 30]
Shape: (3,)

2D array with 1 row: [[10 20 30]]
Shape: (1, 3)

2D array with 1 column:
[[10]
 [20]
 [30]]
Shape: (3, 1)

Mistake 3: Not understanding data type

# Mixing integers and floats
mixed_list = [10, 20, 30.5, 40]
print(f"Mixed list: {mixed_list}")
mixed_array = np.array(mixed_list)
print(f"NumPy array: {mixed_array}")
print(f"Data type: {mixed_array.dtype}")
print("⚠️ NumPy converts all to same type (float in this case)")

# All integers stay integers
int_list = [10, 20, 30, 40]
int_array = np.array(int_list)
print(f"\nInteger list: {int_list}")
print(f"NumPy array: {int_array}")
print(f"Data type: {int_array.dtype}")
print("✅ All integers stay integers")

Mixed list: [10, 20, 30.5, 40]
NumPy array: [10.  20.  30.5 40. ]
Data type: float64
⚠️ NumPy converts all to same type (float in this case)

Integer list: [10, 20, 30, 40]
NumPy array: [10 20 30 40]
Data type: int64
✅ All integers stay integers

Summary

In this notebook, we've covered some essential and practical aspects of using NumPy in Python:

• How to create arrays and the differences between Python lists and NumPy arrays
• Common mistakes, including operating on Python lists vs NumPy arrays, mixing data types, and misunderstanding array shapes/dimensions
• Useful attributes such as .shape and .dtype
• Conversion between 1D and 2D arrays and understanding reshape behavior

I spent approximatelly 1 hour every day in a week to learn, play, expermiment and write this notebook. If I did it, you can too!

Topics for Further Learning

If you wish to deepen your NumPy skills, consider exploring the following:

• NumPy array broadcasting rules and how they apply to arithmetic operations
• Advanced indexing and slicing techniques (fancy indexing, boolean indexing)
• Vectorized computations for performance improvements
• Useful NumPy functions: np.dot, np.linalg, np.random
• Memory layout and the difference between np.copy() and view/reference semantics
• Integrating NumPy with pandas and plotting libraries like matplotlib
• Working with higher-dimensional arrays and practical applications in scientific computing

Would Cursor be better for my work? Or Wind Surf. No, man, try Claude Code. Which model? Sonnet 3.7 or 4? I’d suggest GPT-4 or 5. No, no, use GPT-5 for writing CSS, and then Sonnet-4 for writing JavaScript.

Don’t forget about .cursorrules and claude.md. You need to write a ton of documentation so your agents know how to do their jobs. You need to create separate agents for the frontend and backend, and even break them down further to make them work well for you.

The prompt can’t be too large or too small. It has to be just right. You need to test different prompts, in various tasks and with other models, and figure out which one works best when. It’s best to create an Excel prompt library.

A new version of the tool came out, and it stopped working. Oh well, experiment again. You’ll surely find the best way to explain to the bot how to write the code for you.

That’s how I see it, working with AI tools. I’ve been through all of this myself, having tried it from the very beginning. Isn’t that pathological? Isn’t it analogous to those nerds who spent an hour configuring Neo Vim?

Devs say they feel productive and work faster, but is that really the case? The illusion of productivity is certainly compelling, and using these tools can make you feel like magic is happening.

Productivity illusion

Developers feel productive when they configure these tools. They feel like they’re riding a wave and doing something super good. I’ve done it myself. Anyone who wants to try AI coding tools has to do it, because in real life, these tools don’t help without all the machinery I described above.

The problem with configuring this tool is that it’s not something you can finish. You’ll spend hours configuring it, but in reality, you can tell the AI ​​to do the same task five times and it’ll do it differently each time. Or you’ll make a tool update, and what you thought worked no longer works.

But configuration and improvement give you a boost. You feel better. You’re working on something that’s mega-popular right now, so you feel satisfied. You can even give presentations and share your knowledge. In the long run, you’ll deliver just as many features as without it. No one can really measure its actual impact on productivity yet.

We can measure it through the hype of X and YouTube, and we do, which only reinforces the false narrative.

We measure the wrong things

A developer sees that an AI tool has generated a ton of code and a dozen or so files and is delighted. Does more lines of code, more files mean better? It should be the other way around: the less code you write to solve a problem, the better for you and others.

AI generates a ton of code, and you can feel the vibe and accept it, but I deeply believe that serious developers who use agents and prompts to generate code, review it, improve it, and refactor it.

It takes time. Sometimes it’s actually faster to refactor something using prompts, but not always. You feel 10x faster, but maybe you’re actually 20–30% faster — we don’t really know how to measure that.

Another thing is that writing code has never been the biggest challenge in software development. It’s much more difficult, for example, to understand what the Product Owner means when presenting a new design.

Or debugging a bug in a distributed architecture, when, at best, it takes you a few hours to find a way to reproduce the problem.

Creating new code is only a small part of everyday software development work. Unfortunately, we have focused so much on optimizing code generation and adding new features that we have forgotten about it, leading us into a vicious cycle of investing time in optimization.

This is a sandcastle

Referring back to configuring NeoVim. You know, I started using NeoVim about six months ago. I struggled terribly at first, but once I configured it to my liking, it worked for me, and I didn’t have to change many things later. Configuring AI coding tools is quite the opposite.

Every few months, new models are released, and prompts that worked perfectly yesterday might be fit for the trash today. There are more and more tools, and thanks to powerful marketing, we’re bombarded from every side with gibberish about the superiority of tool A over tool B.

You configure something that works now. In three months, you’ll have to configure it differently. You learn techniques that will be forgotten next year, and you’ll be learning even more. This investment doesn’t pay off. You pay more for it than you think.

The real cost isn’t just wasted time, but also avoiding difficult work and learning technologies that will truly benefit you when you want to become an expert.

These tools won’t help you when you have a huge codebase and need to fix edge cases. They won’t help you discuss a new feature with the Product Owner or understand another developer’s intentions. They won’t resolve conflicts within the team or conduct a security audit. Those are the complex parts of our daily work, not code generation.

By spending time forcing technology to write code for you, you’re doing something relatively technical and easy, and it’s a form of “productive procrastination.”

Conclusion

Living and working in the AI ​​bubble, we need more data and less hype. Each of us needs to experiment and find a way to determine whether something works. Just realizing how much time goes into configuring this technology is eye-opening.

You also need to find a balance in using these tools. You don’t have to use them 100% of the time. Sometimes you just write the damn function yourself. NeoVim users configured it to be better at crafting. We configure AI tools to avoid crafting.

#blog #SoftwareEngineering #ArtificialIntelligence #AI #AISkills #Programming #Productivity #AiCoding

Why Omarchy

On my desktop computer, I use Pop OS, and on my company computer, Ubuntu. Initially, I also wanted to install Ubuntu on my new laptop so I could have a similar system everywhere. I learned about Omarchy by accident. A friend sent me a https://youtu.be/gcwzWzC7gUA?si=OFmgDrREa3eesvPo in which DHH showed how to install Omarchy and what it is.

Later I watched https://youtu.be/TcHY0AEd2Uw?si=omIh2Y6188X2w4yq from official https://omarchy.org website and I was so impressed and decided to give it a try.

Basically, I didn't believe that it is possible to install something based on Arch Linux in a few minutes and it can actually work.

Until now, I'd only had experience with Ubuntu and was satisfied. What prompted me to try Omarchy was the many features preinstalled and prepared for web development, as well as Hyprlnd and Tiling Windows.

Installation

I'd heard that installing Arch Linux was incredibly difficult. I'd also seen DHH install Omarchy on an instance in minutes, and it worked, even though Omarchy is built on Arch. I said, "I'll check it out," downloaded the Omarchy ISO image, burned it to a USB flash drive, and ran Framework 12 on my laptop.

I was very positively surprised because everything worked the first time and I saw the beautiful Omarchy desktop:

I thought, cool, but I definitely won't be able to connect to Wi-Fi... Well, it worked the first time, amazing!

BTW, you can see that the name of one of my Wi-Fi networks is "ReactJS"; it's from when I worked primarily as a frontend developer and I actually liked React. Nowadays, I don't like React as much as I did then, but I am too lazy to change the name of the network.

First feelings

When it comes to aesthetics, I'm a bit of a weird person. On the one hand, I like simplicity, which is why I feel so comfortable in the Terminal. On the other hand, I'm also drawn to all sorts of graphical flourishes.

The Windows look is awful, I can't stand it. Mac OS looks better, but you have to ask Apple for permission to do anything, which is annoying.

And Omarchy is nice, it's beautiful. It's functional. It combines two worlds – TUI apps and Web Apps. DHH mentioned this in his talk, and I buy it:

On one side, Neovim in Terminal, full of old-school features, and on the other, Spotify, a modern invention. These two apps can be open side by side. Omarchy allows you to define your own apps, including native apps, web apps, and TUI apps.

Another example: on the left, Lazy Docker as a TUI app, and on the right, my website as a web app:

Default apps

Omarchy comes with a ton of preinstalled software, especially for web developers. So immediately after install, I could use Neovim, Alactricity, and Docker. But not only apps for development. You can also find other useful apps installed by default, like Spotify, Signal, and Obsidian. On the other hand, I found apps that I don’t want to use, such as 1Password. The only minor issue is that you get a lot of stuff installed—some of which you might not like. It's not a big deal because you can easily uninstall it (which I'll talk about later).

Keybindings

Omarchy focuses on using the keyboard as often as possible and provides several useful Key Bindings. SUPER key + Enter opens the terminal, SUPER + number from 1 to 5 switches the workspace. You can open many web and TUI apps using key bindings like SUPER + B, which opens the Browser. Key bindings are well documented. By pressing SUPER + K, you can see instant keybinding documentation: You can also see them, edit, and add new bindings in the ~/.config/hypr/nindings.conf file:

Tilling windows

Tilling windows automatically arrange themselves in a grid or mosaic pattern on your screen, rather than overlapping freely. Instead of windows floating around independently, they tile to fill the available space without overlapping.

After just five minutes of using tiling windows, I knew I'd never go back to the "normal" windows I was used to from Ubuntu, Windows, or Mac. Thanks to Tilling Windows, I can manage my windows and feel more productive.

I can have multiple windows open simultaneously and keep them well-organized. When needed, I can enlarge the active window to full screen size by pressing F11. I can also move the selected window to a new workspace with SUPER + SHIFT + workspace number.

Speed

I won't go into too much detail about the system's speed: on a laptop with an Intel i5, 32GB RAM, it works like Max Verstappen in a Formula 1 car.

Apart from that, I've never had anything freeze, and on my Ubuntu computer, it happens quite often (even several times a week)

Daily usage

The system is stable; I haven't had a crash yet. What I usually do is development in Python and Django. So, I have a database open in Docker, a development server running, Neovim, a few terminals, Spotify, Signal, and other such trivia.

Besides, sometimes I just write (like now), I use Obsidian and a browser for research. It works very well for me, so I'd give it a 10/10. But it can't be that great. There's one thing that really annoys me. I'm talking about the display settings depending on whether I'm working on my laptop or an external screen. Another thing that annoys me, but not terribly, is the occasional problem with installing packages.

Monitors issue

The first unpleasant thing is that every time I connect my laptop to an external monitor, I have to change the settings in .config/hypr/monitors.conf. If I don't do this, everything is too small on the external monitor. Similarly, when I disconnect the laptop from the monitor and want to work on the laptop screen, I have to change the monitor settings, because otherwise, everything on the screen is too large.

The second problem is that when I have my laptop connected to my computer, the workspaces don't function correctly. The thing is, you have five workspaces, and logic tells me that there should be separate workspaces for the external monitor and the laptop screen.

But the workspaces are shared, and it can get confusing. For example, you're on workspace 1 and you see something different on the laptop, such as a browser, and something else on the external monitor, such as a terminal.

When you switch workspaces, the changes are reflected on one screen, while the other screen remains unchanged.

De facto, it works like this: you have five workspaces on one screen and one on the other.

Problem with installing packages e.g. firefox

I once ran into a problem where I couldn't install a package from the Omarcha repositories. Fortunately, I could do it using the AUR, so it wasn't a big deal.

For whom Omarchy

As a car enthusiast, I can say that Omarchy is comparable to an Alfa Romeo. When everything works, you're thrilled, but when something starts breaking, you start to get annoyed. Fortunately, I didn't experience any major problems at first, so my experience has been very positive. I'd love to write a post next year about "Omarchy after a year of using it." In that time, I have a lot to catch up on and learn, especially about Arch Linux and Hyprl.

Summary

So, yes, I plan to stick with this distro! It's the perfect distro for web developers and programmers. In my opinion, it's for people who already have Linux experience. If you're just starting out and migrating from Windows or Mac, I suggest starting with Omakub. It's a different distro from DHH, built on Ubuntu. It might be easier to get to grips with when starting out in the Linux world.

The biggest advantage of Omarchy is its appearance and functionality. It provides significant benefits in terms of work ergonomics. It provides default apps and setup for development. I would rate it 10/10, but due to an annoying issue with monitors, I need to be more strict and give it, let's say, 9!

Published: 10/17/2025 #blog #linux #omarchy

I purchased a brand new Raspberry Pi 5, a cooler, and an external USB drive. I also needed to run an Ethernet cable to my office garage, which I should have done a long time ago anyway.

NextCloudPi. It should work, but it shouldn't work for me

My initial attempts to launch NextCloud were unsuccessful. I couldn't even get past the first launch. Here are the errors I encountered:

[FAILED] failed to start avahi-deamon.service - Avahi mDNS/DNS-SD stack
run `systemctl status avahi-daemon.service` for details

[FAILED] failed to start systemd-logind.service - User login management

[failed] failed to start bluetooth.service -

[failed] failed to start udisk2.service - disk manager

[failed] failed to start dbus.service - D-Bus System message bus

I tried to fix them, but I couldn't even log in because the system never finished the first boot. It was frustrating. At least as frustrating as Dembele winning the Ballon d'Or (okay, a little less so).

Imagine that even a restart didn't help. Nor did turning it off and on. Interestingly, I downloaded an older version of NextCloudPi, but I still had no success. I tried two versions: v1.55.3 and v1.55.2.

It's open-source software, developed by the community. No one said it would work, and I don't blame anyone for it not working. Perhaps there was something wrong with my configuration. I didn't pursue the issue further; I just tried a different approach.

NextCloud on Docker. It must work

I did a small research and I have found this guide: https://help.nextcloud.com/t/guide-setting-up-nextcloud-on-raspberry-pi-ssl-advanced-app-support-high-performance-postgresql-and-cloudflare-zero-trust-integration/185757]. It was good as a starting point.

But it couldn't just work, right?

"Data Directory Invalid" Error

I initially ran NextCloud on an SD card, but ultimately wanted to store the data on an external SSD. I achieved this by setting the datadirectory as a Docker volume, mounted on an external drive.

/media/frodigo/nextcloud-data:/var/www/html/data:z

After restarting NextCloud I saw this error:

Data directory is invalid.
Make sure there is a file called ".ncdata" in the root of the data directory.
The data directory is not writable.

I did a research and I have realized that Nextcloud requires a specific marker file .ncdata in the data directory root to validate the directory structure.

I checked if the file exist, and It didn't exist so I created a new one:

# Check if the file exists
ls -la /media/frodigo/nextcloud-data/.ncdata

# Create if missing
echo "# Nextcloud data directory" > /media/frodigo/nextcloud-data/.ncdata

However, that didn't completely resolve the issue. I moved forward a bit, but then saw another error saying that the data directory is not writable.

User ID Mismatches

Initially, I set permissions on the data directory so that the www-data user could access it. To my surprise, it turned out that the www-data user ID on the host was different from the www-data user ID in the container, which is why I was experiencing problems.

• Host system www-data user: UID 33
• Container www-data user: UID 82

The solution for this problem was to align file ownership with the container's expectations:

# Check what UID www-data has inside the container
docker exec -it nextcloud id www-data

# Set ownership to match container UID
sudo chown -R 82:82 /path/to/nextcloud-data/
sudo chmod -R 755 /path/to/nextcloud-data/

Troubleshooting workflow

When facing data directory issues:

1. Verify the external drive is mounted: df -h
2. Check Docker volume mappings: Review your docker-compose.yml
3. Inspect file permissions: ls -la /path/to/data/
4. Check container user IDs: docker exec -it container_name id www-data
5. Verify .ncdata file exists and is readable
6. Restart containers after making changes: docker-compose down && docker-compose up -d
7. Debug container user context: docker-compose exec -u www-data nextcloud touch /var/www/html/data/test.txt

Note: Docker introduces multiple abstraction layers that can mask the root cause of issues. The key to successful troubleshooting is understanding these layers and testing each one systematically. Always verify your assumptions at each level:

• network connectivity
• volume mounting
• file permissions,
• application configuration

It works. Somehow

After overcoming these setbacks, my NextCloud on Pi started working, but it seems this is more the beginning of an adventure than the end. The rest of my adventures might come in the near future, if I don't give up. We'll see.

Published: 24/09/2025 #blog #nectcloud #raspberrypi #diy #cloud #docker

Autogenerated RSS feed on Obsidian publish is really simple. I realized it when I talked with my colleague and he asked me about RSS feed. I shared a link with him. He added it to his RSS reader. I saw it. It looked like something hastily written. Just titles, nothing. I felt a bit ashamed.

TL;DR

• Obsidian Publish's default RSS feed only includes titles and links - no content or descriptions
• After sharing my RSS feed with a colleague, I felt motivated to create a better one
• Built a custom RSS generator that converts Markdown files to feeds with full content
• Implemented special handling for Obsidian's wiki-style links to maintain proper formatting
• Deployed the feeds to Cloudflare Pages with a custom subdomain
• Created two versions: one with all content and one with just recent posts
• Future improvements include code refactoring, category-specific feeds, and simpler hosting via GitHub

I investigated why quality of my feed was so bad. It was because in feed generated by Obsidian, there are only two fields for each item: title of an article and link to it.

<item>
	<title>Historical cryptography algorithms</title>

	<link>
https://frodigo.com/Blog/2025/Historical+cryptography+algorithms
	</link>
</item>

So it is not very usable, because someone who uses RSS feeds can only see titles and use link to go to the website.

But what I like the most when I use RSS feeds is to have possibility to read content without need to go outside.

So for me proper RSS feed item looks like this:

<item>
	<title>
		<![CDATA[ Historical cryptography algorithms ]]>
	</title>

	<description>
		# short description like first paragraph
	</description>

	<link>
https://frodigo.com/Blog/2025/Historical+cryptography+algorithms
	</link>

	<guid isPermaLink="false">
	https://frodigo.com/Blog/2025/Historical+cryptography+algorithms
	</guid>

	<pubDate>Fri, 28 Mar 2025 00:00:00 GMT</pubDate>

	<content:encoded>
		# full content here so I can read it in my RSS reader
	</content:encoded>

</item>

In this example you can see that there is description field that shows something like excerpt. Also there is a content field which contains a full content of an article.

I tried to find how to implement something like this using Obsidian publish, but I didn't find a way.

So I started to thinking how to implement it by myself.

And I came up with this idea:

• create RSS feed from my markdown files
• deploy it somewhere
• add link to it on my website

Creating RSS feed

In my astro blog I had a script in JS that generates RSS feed so I have used it as starting point

I needed to adjust it a little bit. I needed to implement support for links in Obsidian Wiki format like [[link]] or even [[this is link|this is a text]].

Also I wanted to have an option to specify which content should be in feed and which not. On my website I have a few pages that can be considered as blog article (like this one). Besides, I have a lot of content that is just my Notes, and I don't want to spam people with anything that comes to mind.

I didn't have to much time so I used Cursor to adjust this script to my needs.

I was disappointment about results. Cursor was not able to implement link formatting in a acceptable way. Cursor generated hundreds of lines of code for simple feature.

In addition, when I asked it about writing tests, cursor started do things like a drunk programmer.

So I landed with an overcomplicated solution. But it works.

How it works:

• Markdown in → RSS out: scans my project for dated .md notes and turns them into two RSS files
• Obsidian link handling: understands [[Wiki Links]], cleans up internal URLs, and keeps external links unchanged.
• Auto metadata: pulls title, date, description, categories, and optional hero image from each file’s front‑matter.
• Feed hygiene: sorts by date, skips undated posts, and embeds full HTML content in <content:encoded>
• Post‑build sanity check: extracts every internal link from the feed and writes them to links-to-test.json for automated link‑testing.

This is the full implementation: https://gist.github.com/Frodigo/bbcf18db7e431cfcbb31f6fb13dd9cd6

Here is the most interesting part:

// --- Link‑handling magic ---
function configureMarkedRenderer() {
  const renderer = new marked.Renderer();

  renderer.link = (href, title, text) => {
    // Extract URL from href if it's an object
    const hrefStr =
      typeof href === "object" && href !== null
        ? href.href || href.url || "#"
        : String(href || "");

    // Extract text content if it's an object
    const textStr =
      typeof text === "object" && text !== null
        ? text.text || text.title || hrefStr
        : String(text || hrefStr);

    // Handle wiki links
    if (hrefStr.startsWith("[[")) {
      const linkText = hrefStr.slice(2, -2);
      const url = generateUrl(null, linkText);
      return `<a href="${url}">${textStr}</a>`;
    }

    // For regular links, extract the last part of the URL for the text and decode it
    if (hrefStr.startsWith("https://frodigo.com/")) {
      const lastPart = hrefStr.split("/").pop();
      const decodedText = decodeURIComponent(lastPart.replace(/\+/g, " "));
      return `<a href="${hrefStr}">${decodedText}</a>`;
    }

    // For regular links, ensure proper formatting
    return `<a href="${hrefStr}">${textStr}</a>`;
  };

  marked.setOptions({
    renderer,
    mangle: false,
    headerIds: false,
  });
}

function processWikiLinks(html, filePath, config) {
  return html.replace(/\[\[(.*?)\]\]/g, (_, link) => {
    const [target, label = target] = link.split("|");
    const url = `${config.site.site_url}/${generateUrl(null, target)}`;
    return `<a href="${url}">${label}</a>`;
  });
}

(funny thing: when I added this snippet to codebase, I needed immediately fix the generator because it generated links from the code snippet...)

These two functions are responsible for handling and parsing links.

processWikiLinks() runs over the freshly rendered HTML and turns any remaining [[Wiki Link|Label]] syntax into fully qualified site URL.

I didn't trust to this Cursor generated code and I needed to created a e2e tests that checks that all links in generated feed are ok.

I set up Playwright for that and wrote simple test: https://gist.github.com/Frodigo/e1577910f92c0619b21b7d1c9de4c5a1

Deploying RSS feed

I tried to upload generated xml files to Obsidian Publish "server", but it is not possible

So I decided to create a simple static website (used CLaudflare pages for that) and I deployed generated feeds there.

Also I created a Github action that automatically generate feeds and deploy them to Cloudflare: https://gist.github.com/Frodigo/a129e1914fea25156dfd2907d9a65940

In addition I set up subdomains and it the end I have two RSS feeds available:

• All items: https://rss.frodigo.com/feed.xml
• Recent 10 items: https://rss.frodigo.com/feed.recent.xml

Showing feeds on my Obsidian page

This was an easy one. I have just written a section on my homepage and added links there.

Wrap up

I needed a few hours to generate this feed and deploy it to the server and now I have my RSS feed.

I see some potential improvement that I can make:

1. Before everything I have to refactor the code, because I feel it can be 5 times more simple when human writes it.
2. I want to have separate feeds for categories
3. I realized that instead of deploying generated feed to Cloudflare I can just generate it and keep in version control. My repository is public so I can just use a raw version of file from Github and it should work

All of these items I will do before I die. If so, I will write about them in the separate article.

I am wondering how to do this changes in a way that someone else can have such a nice RSS feed on their Obsidian page. Maybe Obsidian plugin? If you think is interesting, let me know!

Published 17/04/2025 #blog #Obsidian #ObsidianPublish #WebDevelopment #ContentSyndication #JavaScript #StaticSite #BloggingTools #WebAutomation #Markdown #GitHubActions #CloudflareSites #KnowledgeManagement #DigitalGarden #RSSFeeds #ContentCreation #WebsiteCustomization #AIAssistants #ProgrammingChallenge #PersonalProject #FrontendDevelopment #NodeJS #Git #CI/CDtools #Cloudflare #Tutorial #CaseStudy #ProjectSetup #Intermediate #APISecurity #AutomatedTesting

— I can’t wait for our new kitchen, wife said. She wanted to have a new kitchen for months, because she was frustrated that the furniture was falling apart and was impractical.

When she was cooking and something wasn’t working out for her, she would approach her husband and say — When are we finally going to do this renovation?

— I will make this soon, I promise, he answered.

— You, why don’t we hire professionals for this? Wife asked with some kind of irritation in her voice.

— I am a professional, you will see! He said firmly, and a rather obvious spark was visible in his eyes!

This is how I, the programmer who likes DIY, got myself into a kitchen renovation. Something that seemed like it would be fun. But what was it really like?

Well, I confirmed all the well-known life laws that I am aware of during this renovation.

The fact that I survived and I write it is the best thing that could happen. Besides, another important thing — I still have a wife!

Murphy’s Law

“If anything can go wrong, it will.”

The timeline for this renovation was short:

1. 1 day to dismantle old furniture
2. 2 days to remove old tiles and prepare the walls for new ones
3. 1 day for making changes in electricity (adding new electrical sockets and additional wiring for new lighting)
4. 3 days to install new tiles and paint the walls
5. After 7 days, a team should come to assemble the new furniture

For each point, I could write a separate story, but I’ll spare myself that today and move on to the climax.

After seven days of hard work, after dealt with various unexpected things.

When I had about 10 tiles left to lay, I opened the last package of tiles.

I could already imagine myself laying the last tiles, then reaching for the grouting and the job would be done. I could already feel the pride when my wife would come and say: “You’re a hero, my husband!”

I opened the last box.

And I thought I was going to go crazy. It turned out that the last package of tiles was different tiles I ordered. I didn’t check it beforehand.

I turned red in the face and started walking around, cursing under my breath. My wife looked at me with sympathy.

I thought I would go out of my mind and stand next to me. Oh, good that the tile seller who made a mistake wasn’t there because https://www.instagram.com/reel/DINr85_TeCK/?igsh=MWgxdnpiN3ZubW5xbA%3D%3D. How could you have made such a mistake?

I couldn’t finish, and the next day they were coming to assemble the furniture.

I filed a complaint and ordered new tiles, but I had to wait two weeks for them.

“If anything can go wrong, it will.”

Yhprum’s Law

The opposite of Murphy’s Law. It states:

“Everything that can work, will work.”

I have called a professional from the company responsible for new furniture and asked if it’s possible to start with furniture when the tiles are not done yet.

— Of course, he said. We can do our job and mount new furniture. When we're done, you can continue working with tiles.

It seemed strange to me, but if an expert says so, it must be so, right?

“Everything that can work, will work.”

Guess what? When they finished the furniture and I started again with tiles, I had a serious problem finishing them.

I had to be careful not to get anything dirty or mess it up. Murphy's law — again!

Parkinson’s Law

This law suggests that work expands to fill the time available.

And here is the most important law.

Because you know, it’s been a few weeks since this renovation.

The kitchen is supposedly finished, but there’s some silicone missing here. In another place, the socket would have to be fixed. One lamp is still not replaced.

But Parkinson’s law comes into play. Because as long as I live, I have time to finish this job ;-)

Conclusion

As I stand in my almost finished kitchen. I laugh thinking about how confidently I said, ‘I am a professional, you will see!’

The funniest part of all of these laws is that they fit into every situation. Perhaps the only law that truly matters is the one you choose to believe in.

Actually, I believe that next time, when I do a kitchen renovation, I will complete it 100%.

And that I will do it together. With the same wife.

Sources

• https://en.wikipedia.org/wiki/Murphy%27s_law
• https://en.wikipedia.org/wiki/Yhprum%27s_law
• https://en.wikipedia.org/wiki/Parkinson%27s_law

Published 13/04/2025 #blog #diy

I was sitting at my computer, trying to solve a deployment problem with my application, when my son came into my home office. He sat off to the side and watched quietly for a while.

“What’s up, son?” I asked, turning my attention to him.

“Dad, what exactly are you doing here?”

I began explaining to him that I was programming. We talked for a bit, and in the end, he said, “Dad, I want to be a programmer like you!”

At that moment, I felt a spark of satisfaction and pride run through my entire body. I’m sure there was a twinkle in my eye.

TL;DR

• Teaching kids to code isn’t as easy as sharing your programmer passion
• Start with visual block-based coding (like Scratch) instead of text-based languages
• Use learning platforms like code.org rather than creating your own projects
• Create consistent session structures and rituals for better learning
• Visualize abstract concepts and break complex processes into smaller steps
• Be patient — learning happens about 150 times slower than you might expect
• Prioritize fun and enjoyment over rapid progress

First computer and playing games

It’s amazing how children try to imitate their parents, isn’t it?

I said to him, “It’s time, my son. It’s time for you to have your first computer.”

Up until then, I’d tried to keep him away from the cyber world, from phones and computers. But if he wanted to be like Dad, well, there was no point in delaying anymore.

And so my son got a Raspberry Pi 400, which was supposed to be the beginning of his programming journey.

But of course, we started with playing games. (I bought PiMiga — an Amiga emulator for Raspberry Pi — and we played quite a lot, but that’s a topic for another story, I think.)

First program

After some time, we started programming. On a Raspberry Pi, you can easily begin writing Python code. Our first program was about counting how much time we spent playing on the computer.

My son really likes Super Mario and math, so we created simple programs on these subjects. I tried to make it interesting for him.

What’s funny is that this was also my first time coding in Python. For some reason, I had been avoiding this language before, but since then, I’ve actually grown very close to Python.

Things become boring

After the initial excitement, problems appeared.

“Can we play this? Can we play that? But why do I have to turn it off now?” These were questions from a child who had already forgotten that he was supposed to become a programmer.

Ah, these games — had they ruined everything? I tried to educate my son about how long he could use a computer and how to use the internet safely. Despite this, he was losing interest.

Unfortunately, there was a competition: programming vs. gaming, and programming had no chance in this fight.

And that’s how I came to the conclusion:

Teaching kids programming is demanding

I realized how naive I’d been to try teaching my child programming without any preparation.

We were struggling with:

1. Abstract thinking — It’s hard for children to connect abstract concepts like loops, variables, and functions with real life.

2. Motivation — My son wanted to see results immediately, but coding often requires patience before seeing outcomes.

3. Excessive Screen Time — Five minutes of actual programming required more than half an hour in front of the screen because I needed to explain concepts first, provide encouragement, demonstrate examples, and of course, allow time for games.

4. Teacher competency — I wish I were a good programming teacher, but I’m not. Programming and teaching programming are two different skills. Additionally, teaching adults how to code is quite different from teaching kids. There’s simply no way to be an effective teacher for children without proper preparation.

Teaching kids programming is demanding

The second chance

I can sum up this first period of teaching as a difficult start. But it’s not that bad — I showed something to my child, drew conclusions, and we can continue.

This is what I learned:

1. Block-based coding is better for starting than text-coding

Instead of starting with Python, I could have used Scratch and similar interactive tools that teach programming in a more visual way.

Block-based environments allow children to see programming concepts represented as tangible elements they can manipulate, making abstract ideas more concrete and approachable.

2. Use established learning platforms instead of creating your own projects

I initially thought I would easily come up with interesting projects and coding ideas. However, it wasn’t that simple. Now I use platforms like https://code.org/ and https://www.gov.pl/web/koduj (a Polish resource) to guide our learning, and it’s much more effective for both of us.

3. Build rituals and repeatable session structures

I’ve noticed better results when my son knows exactly what to expect from each lesson. Having a consistent structure for what we’ll do during the session and afterward creates a sense of familiarity and security.

Additionally, I now spend more time reviewing what we learned previously, discussing what we’re working on currently, and previewing what comes next. These regular summaries and repetitions have proven remarkably effective.

4. Visualise concepts and simplify complex processes

I try to relate abstract programming concepts to familiar, concrete objects or experiences. Analogies help connect new information to my son’s existing knowledge base, making difficult concepts more accessible.

When something is challenging to explain, I break it down into smaller pieces and tackle them one by one. This step-by-step approach prevents overwhelm and builds understanding progressively.

5. Don’t force anything

Learning works best when it’s fun and enjoyable. The hardest thing for me to accept was that the pace of learning is about 150 times slower than what I would prefer as a teacher. However, I’ve learned that adapting to my son’s pace and finding joy in the process leads to more sustainable progress.

Lessons Learned

Good luck

Teaching programming to kids requires luck, considerable strength, and abundant patience. I wish you success on this rewarding journey!

And may your child become an even better programmer than you!

Published 07/04/2025 #blog #ProgrammingFundamentals #Python #BestPractices #ConceptExplanation #CaseStudy #Beginner

But the reality is different. In this article, I’ll share the mistake I kept repeating — and what I wish I had done differently if I could turn back time.

My first blog. Source: https://web.archive.org/web/20170710170315/http://marcin-kwiatkowski.com/

TL;DR

Programmers who want to be writers should focus on writing, not on endlessly rebuilding their blog platforms.

If I could turn back time, I’d stop chasing the perfect blog setup and just write. Reinventing the wheel was a great excuse to avoid the hard part: writing.

My first steps into the trap

My first blog was a WordPress site written in Polish — a solid choice to get started. The quality of my content wasn’t great, but I enjoyed it. I felt like I was making progress, and each new post was a little better than the last.

Chasing performance, losing Purpose

A few years later, I worked on a project using React and Next.js — and I was impressed. I thought, why not build my blog with it and fully customize the experience?

What could go wrong?

I spent weeks crafting my shiny new blog platform. Then more weeks importing posts from WordPress. I even chose Storyblok as a headless CMS. It was a big re-platforming effort, and during that time, I wasn’t writing anything new.

I believed that a Next.js blog would be blazing fast and score perfectly in PageSpeed Insights. And it did.

But now I know: the most important part of a blog is the content — not whether it gets a score of 100 or 45.

Honestly, I never even finished implementing all the features I had planned. After a few months, I realized it wasn’t as good as I’d hoped.

Writing on WordPress was easier.

Blog on NextJS (unfortunatelly CSS doesn’t work in the archive so it looks ugly. Source: https://web.archive.org/web/20210602071506/https://marcin-kwiatkowski.com/

Wordpress again

After failing with my custom setup, I decided to go back to WordPress — which meant more weeks spent on yet another migration.

This time, I also set up a multilingual platform. I thought I could write in both Polish and English at the same time.

It kind of worked. But I quickly realized it wasn’t as easy as I had imagined. Instead of focusing on writing good content, I was spending my energy on translating.

(Later, I started using AI for that — but that’s another story.)

I should have resisted the hype and shiny new tech — but I didn’t.

Every new tool fascinated me, and I kept running away from what truly mattered: improving my writing and actually writing.

Instead, I jumped from one technology to another like a man possessed.

New Wordpress blog (also CSS is broken in archive). Source: https://web.archive.org/web/20230606020832/https://marcinkwiatkowski.com/

Go away from WordPress again and migrate to Astro

Then I met astro.build and I was fascinated. I thought that a static website with Markdown as an engine for content is a good idea (and of course it is).

I migrated to Astro. I spent a lot of time because this time I thought that I needed to use this re-platforming opportunity to create a beautiful blog. It was kinda beautiful.

Blog migrated to astro. Source: https://web.archive.org/web/20241005174031/http://marcinkwiatkowski.com/

I was really satisfied with this implementation. I wrote more about this here: https://medium.com/gitconnected/how-and-why-i-moved-my-blog-from-wordpress-to-astro-and-markdown-3549672d5a86

Writing in Markdown is perfect. I also started using Obsidian. I could focus more on writing. Anyway, I still used a lot of my time on improving the blog platform, refactoring, adding new features, optimizing, etc.

The AHA moment

In February, after a 10-year break from engineering studies, I started my master’s degree.

During one of the first lectures, something the lecturer said made something click in my head.

It was a Saturday, already late — around 6 p.m. We were sitting in a small classroom, everyone visibly tired. The kind of moment where you’d expect nothing meaningful to happen.

And yet, that’s exactly when it did.

The lecturer was an older professor with a sharp sense of humor. His shirt peeked out from under a worn sweater, and his piercing gaze made you pay attention.

There was something about him — calm, thoughtful, quietly commanding.

What truly stayed with me was something he said during that lecture. He spoke slowly and clearly about what awaits every student: the master’s thesis.

He said something like this (I’m paraphrasing):

If your master’s thesis is truly good, you can write it by hand with a pen — and your supervisor will copy it himself, because he’ll know it’s worth the effort. But if your work is weak, even if it looks beautiful and polished, no one will care.

This is a very interesting point of view. It may be obvious, but it made me reflect on how I approach writing.

I thought, do I really want to be a writer, or am I just pretending?

Facing the truth about my writing

It was hard to face the truth: I hadn’t been focusing on the right thing.

At one point, I even asked myself — maybe writing isn’t for me? Maybe I’m just pretending?

Still, I gave myself another chance.

So… what did I do?

Replatformed again. 😅

This time, I ditched the beautiful Astro website and went back to basics. I stuck with Markdown and write in Obsidian.

Now, Obsidian is my writing engine. My website is plain — some might even call it ugly. But I don’t care.

I’m finally focusing on what matters: writing.

My new ugly website. Source: https://frodigo.com

So now I’m writing — and I’ve made a deal with myself: no replatforming for the next year.

Just writing.

Can I stick to it?

We’ll see.

Published: 04/05/2025 #blog #writing #BloggingTools #SoftwareEngineering #Productivity #PersonalGrowth

Programmers who want to be writers should focus on writing, not on endlessly rebuilding their blog platforms.

If I could turn back time, I’d stop chasing the perfect blog setup and just write. Reinventing the wheel was a great excuse to avoid the hard part: writing.

Read more in my Medium story: https://medium.com/@frodigo/how-i-failed-at-writing-a-blog-many-times-d1e5040763a7

Published 05/04/2025 #blog #obsidian #astro

I was sitting in the computer room, it was quite stuffy, and around me were 30 other students. It was the third class of the day. The lecturer came in, who looked like a rather strict gentleman. He explained to us briefly what the course would look like and what the rules were for passing.

The atmosphere began to thicken, and the gentleman promptly moved on to the task. He told us to install Cryptool1 and do a task related to historical cryptographic algorithms.

Cryptool is a free tool for learning cryptography. Okay, let's install it, but wait, wait.

This tool only works on Windows. :facepalm

I did a quick research and found that I can use run Windows program on Mac using Wine. Let's try I thought:

brew install --cask wine-stable

I was pressed for time, because after the exercises we had to write a report.

Unfortunately, internet connection was so poor in that computer room and I was not able to install this tool in 1 hour.

In meantime I used Perplexity to find information about historical crypto algorithms.

I spent the rest of the class reading...

Few days later

I did back to the topic and again installed the Wine, but this time at my home and internet was quite better.

After that I needed to install Rosetta - a tool that allows to run apps dedicated for Intel Chips on Apple chips. Oh really?

To run Cryptool on my mac I needed to install wine (to run Windows app), but to run Wine i needed to install Rosetta

flowchart LR
    A[Mac with Apple Silicon] --> B[Rosetta 2]
    B --> C[Wine]
    C --> D[CrypTool]

I ran Cryptool installer:

wine SetupCrypTool_1_4_42_pl.exe

Then I was able to run it (I installed the polish version)

Algorithms

Ok, so at this moment I can experiment with Cryptool and learn about crypto a bit.

In the scope of task I had: Cesar, Vigenere, Hill and XOR. Let's take a closer look at them

Caesar's cipher

It's one of the oldest and simplest Encryption.md algorithm invented (or at least associated with) Julius Caesar.

Cesar used in in around 58 BC. How it worked? It scrambled a message by shifting its letters. Technically speaking is a Monoalphabetic%20rotation%20ciphers.md it shifts letters by 3, but there is also a variant called ROT-13 that shifts letters by 13.

I implemented the Caesar cipher in C# for learning purposes.

Here you can find:

• https://github.com/Frodigo/garage/tree/main/sandbox/cybersecurity/cryptography/HistoricalCiphersDemo
• https://github.com/Frodigo/garage/blob/main/sandbox/cybersecurity/cryptography/HistoricalCiphersDemo/Ciphers/Caesar/CaesarCipher.cs
• https://github.com/Frodigo/garage/blob/main/sandbox/cybersecurity/cryptography/HistoricalCiphersDemo/Tests/CaesarCipherTests.cs

Before you go to the next cipher, check how the caesar works on diagrams below:

flowchart LR
    A[Plain Text] --> B[Apply Shift]
    B --> C[Encrypted Text]
    D[Key: Shift Value] --> B

flowchart TD
    subgraph "Example"
    E[Plain: HELLO] --> F[Shift by 3]
    F --> G[Cipher: KHOOR]
    end

flowchart TD
    subgraph "Alphabet Shift"
    H["A B C D E F G H I J K L M N O P Q R S T U V W X Y Z"] --> I["Shift by 3"]
    I --> J["D E F G H I J K L M N O P Q R S T U V W X Y Z A B C"]
    end

Vigenère cipher

It's a polyalphabetic%20substitution%20cipher.md which uses a keyword to encrypt and decrypt messages.

How it works?

1. Each letter of the key specifies a different shift
2. Same plaintext letter can encrypt to different Ciphertext.md letters
3. Algorithm takes two inputs: message(plaintext) and key(password).
4. Algorithm prepare key by repeating it to the message length.
5. Then it intitialize empty result string.
6. Next it iterates on each character in plaintext:
7. 1. if a char is a letter, gets corresponding char of key
8. 2. checks is plaintext cha uppercase and calculate Vigenère shift:
      1. for uppercase letter: (P + K) % 26 +65
      2. otherwise: (P + K) % 26 + 97
9. 3. if char is not a letter, it's added to the results unchanged
10. When iteration is done, returns ciphertext.

You can find my implementation of this cipher here:

• https://github.com/Frodigo/garage/blob/main/sandbox/cybersecurity/cryptography/HistoricalCiphersDemo/Ciphers/Vigen%C3%A8re/Vigen%C3%A8reCipher.cs
• https://github.com/Frodigo/garage/blob/main/sandbox/cybersecurity/cryptography/HistoricalCiphersDemo/Tests/Vigen%C3%A8reCipherTests.cs

Take a look on diagram:

---
id: 050da2d7-1974-4ec0-89f9-f9d5ae2c3d33
---
flowchart TD
    Start([Start]) --> InputText[/Input Plaintext/]
    InputText --> InputKey[/Input Keyword/]
    InputKey --> PrepKey[Prepare Key: Repeat to match plaintext length]
    PrepKey --> InitResult[Initialize Empty Result String]

    InitResult --> LoopStart{For each character in plaintext}

    LoopStart -->|Yes| CheckChar{Is character a letter?}
    LoopStart -->|No| EndProcess([End])

    CheckChar -->|Yes| GetChars[Get plaintext char and corresponding key char]
    CheckChar -->|No| AddUnchanged[Add character to result unchanged]
    AddUnchanged --> NextChar[Next character]
    NextChar --> LoopStart

    GetChars --> DetermineCase{Is plaintext char uppercase?}

    DetermineCase -->|Yes| ShiftUpper["Calculate Vigenere shift:
    P = plaintext char code - 65
    K = key char code - 65
    C = (P + K) % 26 + 65"]

    DetermineCase -->|No| ShiftLower["Calculate Vigenere shift:
    P = plaintext char code - 97
    K = key char code - 97
    C = (P + K) % 26 + 97"]

    ShiftUpper --> ConvertBack[Convert code back to character]
    ShiftLower --> ConvertBack

    ConvertBack --> AddToResult[Add shifted character to result]
    AddToResult --> NextChar

    EndProcess --> ReturnResult[/Return Encrypted Text/]
    ReturnResult --> End([End])


    class Start,End,EndProcess terminator
    class InputText,InputKey,ReturnResult io
    class PrepKey,InitResult,GetChars,ShiftUpper,ShiftLower,ConvertBack,AddToResult,AddUnchanged,NextChar process
    class LoopStart,CheckChar,DetermineCase decision

Hill cipher

It's a polygraphic substitution cipher.

It's a block cipher.

It uses linear algebra and matrix manipulation to encrypt and decrypt messages.

How it works

1. Turn letters into numbers
   • A = 0, B = 1, C = 2... Z = 25
2. Break your message into small groups
   • If using a 2×2 key, break into groups of 2 letters
3. Use a special key (a math grid of numbers)
   • The key is a square grid of numbers (like 2×2 or 3×3)
4. Do some math magic with your numbers and the key
   • Multiply your letter numbers by the key grid
5. Turn the new numbers back into letters
6. Done

Example with "HELP"

1. Convert to numbers:
   • H = 7, E = 4, L = 11, P = 15
2. Split into groups: [7,4] and [11,15]
3. Use this key: [3, 2] [5, 7]
4. Math magic:
   • For [7,4]: [3 2] × [7] = [3×7 + 2×4] = [21+8] = [29] → [3] (after mod 26) (because there are 26 letters in alphabet) [5 7] [4] [5×7 + 7×4] [35+28] [63] → [11] (after mod 26)
   • For [11,15]: [3 2] × [11] = [3×11 + 2×15] = [33+30] = [63] → [11] (after mod 26) [5 7] [15] [5×11 + 7×15] [55+105] [160] → [4] (after mod 26)
5. Convert back to letters:
   • 3 = D, 11 = L, 11 = L, 4 = E
   • Secret message: "DLLE"

To decode it, your need the special inverse key to turn "DLLE" back into "HELP"!

For encryption we used this key (matrix):

[3 2] [5 7]

To decrypt the message, we need to find the inverse of this matrix.

You can find a basic Hill Cipher implementation here:

• https://github.com/Frodigo/garage/blob/main/sandbox/cybersecurity/cryptography/HistoricalCiphersDemo/Ciphers/Hill/HillCipher.cs
• https://github.com/Frodigo/garage/blob/main/sandbox/cybersecurity/cryptography/HistoricalCiphersDemo/Tests/HillCipherTests.cs

As you can see implementation of this cipher is quite more complicated that implementation of previous ones (Caeasr, Vigenère).

Take a look at diagram that presents how Hill cipher works:

flowchart TD
    subgraph "Decryption Process"
        CT2[Ciphertext] --> CNV2[Convert Letters to Numbers]
        CNV2 --> BLK2[Divide into n-letter Blocks]

        KM --> INV[Calculate Inverse Key Matrix\nmodulo 26]

        BLK2 --> MM2{Matrix Multiplication}
        INV --> MM2
        MM2 --> MOD2[Apply Modulo 26]
        MOD2 --> CONV2[Convert Numbers Back to Letters]
        CONV2 --> PT2[Plaintext Message]
    end

    class PT,PT2 plaintext
    class KM,INV key
    class CT,CT2 ciphertext
    class CNV,BLK,MM,MOD,CONV,CNV2,BLK2,MM2,MOD2,CONV2 process
    class EX example

Uh, a lot of theory and it's not easy, is it? Let's try to see how it work in practice and do some tasks in Cryptool.

Tasks & Experiments

1. Compare plaintext entropy values ​​for Polish, English and one other selected language

I used these texts:

Polish:

Dzień dobry. Witamy w świecie kryptografii. Bezpieczeństwo informacji jest niezwykle ważne w dzisiejszych czasach. Każdy użytkownik powinien dbać o ochronę swoich danych osobowych. Zastosowanie zaawansowanych algorytmów szyfrujących pozwala na skuteczne zabezpieczenie komunikacji. Język polski zawiera wiele znaków diakrytycznych, takich jak ą, ę, ć, ł, ń, ó, ś, ź, ż, co zwiększa liczbę możliwych kombinacji i wpływa na wartość entropii. Analiza częstotliwości występowania liter w języku polskim może dostarczyć interesujących wyników dla badaczy kryptografii. Polska literatura obfituje w bogate słownictwo i złożone konstrukcje gramatyczne.

Results:

• text has 23 different characters comparing to 26 characters in alphabet
• entropy: 4.26
• max possible entropy: 4.70

English:

Good morning. Welcome to the world of cryptography. Information security is extremely important in today's world. Every user should take care to protect their personal data. The use of advanced encryption algorithms allows for effective security of communication. The English language relies primarily on 26 letters without diacritical marks, which affects its entropy value. Frequency analysis of letters in English can provide interesting results for cryptography researchers. English literature is rich in vocabulary and has its own unique grammatical structures that differ from other languages.

Results:

• text has 24 different characters comparing to 26 characters in alphabet
• entropy: 4.16
• max possible entropy: 4.70

Italian:

Buongiorno. Benvenuti nel mondo della crittografia. La sicurezza delle informazioni è estremamente importante nel mondo di oggi. Ogni utente dovrebbe prestare attenzione alla protezione dei propri dati personali. L'uso di algoritmi di crittografia avanzati consente un'efficace sicurezza della comunicazione. La lingua italiana utilizza l'alfabeto latino con alcune lettere accentate come à, è, ì, ò, ù, che influiscono sul valore dell'entropia. L'analisi della frequenza delle lettere in italiano può fornire risultati interessanti per i ricercatori di crittografia. La letteratura italiana è ricca di vocabolario e ha strutture grammaticali uniche.

Results:

• text has 21 different characters comparing to 26 characters in alphabet
• entropy: 3.92
• max possible entropy: 4.70

My interetations of results

Because entropy is a a measure of unpredictability and polish had has the best score it is more unpredicable than english and italian.

Based on that, polish is a good language for cryptography use cases.

2. Compare the entropy values ​​of pllaintext and cryptogram depending on the algorithm (Caesar, Vigenere, Hill)

I used my polish plaintext and encrypted it using these trhee algorithms.

Results:

Caesar cipher does not increase entropy because it's just shifting letters, but Vigenere and Hill increased it a lot.

Vigenere disrupts the typical frequency of letter occurrence.

Hill is a block substitution cipher that significantly changes the statistical properties of the text.

3. Compare plaintext histograms for Polish, English, and one other selected language

Polish:

Język polski należy do grupy języków zachodniosłowiańskich. Charakteryzuje się bogatym słownictwem oraz złożoną gramatyką. Zawiera wiele znaków diakrytycznych, takich jak ą, ę, ć, ł, ń, ó, ś, ź czy ż. W polszczyźnie występuje siedem przypadków oraz trzy rodzaje gramatyczne. Teksty pisane po polsku mają specyficzny rozkład częstotliwości liter, gdzie samogłoski takie jak a, e, i, o stanowią znaczący procent. Spółgłoski takie jak t, n, r, s, w również pojawiają się często. Rzadziej występują litery q, v czy x, które znajdują się głównie w wyrazach zapożyczonych. Język polski wyróżnia się na tle innych języków europejskich nagromadzeniem spółgłosek, co widać w słowach takich jak "chrząszcz" czy "źdźbło". Niezwykle ważne w polszczyźnie są miękkości i twardości głosek, które wpływają na znaczenie wyrazów. Polski zasób słownictwa jest stale wzbogacany przez nowe wyrazy, często adaptowane z innych języków. Struktura zdań bywa rozbudowana, z wieloma formami czasowników oraz użyciem imiesłowów. Typowy tekst w języku polskim zawiera wszystkie te charakterystyczne elementy, które tworzą niepowtarzalny profil statystyczny naszego języka.

I can see that the vowels A, E, I, O dominate.

English:

The English language belongs to the West Germanic branch of the Indo-European language family. It is widely spoken across the globe, serving as a primary or secondary language for millions of people. English features twenty-six letters without diacritical marks, unlike many European languages. Its alphabet consists of five vowels and twenty-one consonants, though the letter 'y' sometimes functions as a vowel. Frequent letters include e, t, a, o, and i, while less common ones are z, q, and x. English vocabulary incorporates words from numerous languages, including Latin, French, Greek, and German, making it lexically rich and diverse. Grammatically, English has simplified many of its inflectional forms compared to Old English, relying more on word order and auxiliary verbs to convey meaning. Sentence structure typically follows subject-verb-object pattern, though variations exist for questions and certain expressions. This representative text contains all the characteristic elements that create the unique statistical profile of the English language.

I can see that the letter "E" is the most frequent use comparing to "A" in polsih.

Italian:

La lingua italiana appartiene al gruppo delle lingue romanze, derivata direttamente dal latino. È caratterizzata da una ricca sonorità e da un'ampia gamma di vocali. L'italiano utilizza ventiuno lettere dell'alfabeto latino, con l'aggiunta di cinque lettere straniere usate solo in parole di origine estera. Le vocali a, e, i, o, u sono molto frequenti e rappresentano una percentuale significativa del testo scritto. Tra le consonanti, le più comuni sono l, r, n, t e s. L'italiano si distingue per la presenza di consonanti doppie che modificano la pronuncia e il significato delle parole. Gli accenti sono importanti e vengono usati principalmente sulle vocali finali, come à, è, ì, ò, ù. La struttura grammaticale include tre generi (maschile, femminile e neutro, quest'ultimo limitato a pochi casi) e un sistema verbale complesso con numerosi tempi e modi. Il vocabolario italiano è stato arricchito nel corso dei secoli da influenze greche, arabe, spagnole e francesi. Questo testo rappresentativo contiene tutti gli elementi caratteristici che creano il profilo statistico unico della lingua italiana.

4. Compare plaintext and cryptogram histograms depending on the algorithm (Caesar, Vigenere, Hill)

I used polish text and here are histograms:

The Caesar cipher preserves this distinctive pattern but shifts it along the alphabet, maintaining the same frequency peaks but at different letter positions.

More sophisticated encryption methods show progressively flatter distributions.

The Hill cipher displays a much more balanced frequency distribution than Caesar, though some letters still reach around 6% frequency.

The Vigenère cipher presents a histogram with frequencies mostly ranging between 2-6%, making it more resistant to frequency analysis than Caesar but still less secure than Hill, which demonstrates the most uniform distribution of the three encryption methods.

That's enought for today

Oh, I am tired, but I learned a lot:

1. Humanity knew encryption algorithms even before our era.
2. The Caesar cipher is the simplest. It shift letters by a fixed amount. It's also the easiest to break
3. The Vigenère cipher uses a keyword to create multiple shifting alphabets, making it more secure than Caesar
4. The Hill cipher is the most complex, using matrices and linear algebra to encrypt blocks of text
5. Different languages have different entropy values, with Polish showing higher entropy than English and Italian in my tests
6. More advanced ciphers like Vigenère and Hill significantly increase the entropy of the plaintext compared to Caesar
7. Cryptool is a nice tool that allow for experimentation with these algorithms, though setup can be challenging on Mac (in the end I needed to use Windows because Histograms didn't work on my crazy wine-rosetta setup)
8. Implementing these algorithms in code helped me understanding of how they work
9. These historical algorithms are not secure to use in modern world. Anyway it was worth to studying about them
10. At first I thought this topic would be uninteresting for me, but when I got into it quite deeply I had a good time. (The coolest part was of course implementing ciphers in c#)

Sources

During my studying I visited many places in the internet and also used Claude and Perplexity. Below I list all of places where I did read something:

• https://www.cryptool.org/en
• https://www.ibm.com/think/topics/cryptography
• https://en.wikipedia.org/wiki/Cipher
• https://en.wikipedia.org/wiki/Encryption
• https://en.wikipedia.org/wiki/Ciphertext
• https://www.kaspersky.com/resource-center/definitions/what-is-cyber-security
• https://crypto.stackexchange.com/questions/66127/what-is-an-accurate-definition-for-a-monoalphabetic-substitution-cipher-and-wh
• https://pages.mtu.edu/~shene/NSF-4/Tutorial/VIG/Vig-Base.html
• https://www.alrasheedcol.edu.iq/modules/lect/lect/7051-Security%20lecture%2010(%20Hill%20).pdf
• https://bluegoatcyber.com/blog/how-is-xor-used-in-encryption/

Thanks for reading!

Last updated: 22/03/2025 #Cybersecurity #ProgrammingFundamentals #CSharp #Shell/Bash #Git #Cryptool #Tutorial #DeepDive #ProjectSetup #Intermediate #HistoricalCryptography

When my friend told me that Docplanner was looking for a software engineer, I started seriously considering returning to hands-on programming.

The position was interesting for me because I could:

1. Return to hands-on development.
2. Work on a fresh stack (.NET/C# instead of Node.js).
3. Solve problems in a completely new (for me) business domain — healthcare instead of e-commerce.

I had nothing to lose. I made a new CV and sent it. The recruitment process was quite difficult for me, but I did it. I got a job offer and I accepted it.

But, to prepare better for the new challenges, I decided to take a month off from finishing my previous collaboration with Alokai to start a new one with Docplanner.

Preparation

I knew I needed to prepare. It was hard for me to code at all, even in well-known technologies that I worked with daily, like NodeJS/Vue.

It’s truly shocking how out of practice you can get after 3–4 years of being a tech/team leader.

So, I started to think — how to prepare best? For starters, I bought three books, but I actually didn’t read them — only one “Learn C# In One Day and Learn It Well”, but it was short.

Also, I tried a Udemy course but dropped it in the middle, as it was incredibly dull.

What worked like a charm? I just wrote some code in C#. That’s it. Also, I created a project in Claude that helped me understand C# features from a NodeJS perspective. Like this:

My message:

AI assistant answer:

It also showed me implementation in JS:

Screenshots show a trivial example, but this assistant was helpful in learning. It helped me identify the gaps in my knowledge and adapt to the best practices. Or, at least, acceptable practices.

Onboarding

When I started at Docplanner, I was very warmly welcomed and received an impressive onboarding checklist. I had time to meet people and the team.

Then I started learning about the company, products, technology and history.

Actually, it was my first job in my whole career and nobody expected that I would write code from the first day. I had time for everything needed to onboard to the company. Also, I had a buddy who showed me a lot and answered all my questions.

Observation

After the first onboarding tasks, I felt I could start contributing. But, actually, I needed to hold my horses! I tried to understand the project, workflow and technology.

To do so, I have reviewed others' code, pull requests. I did listen to daily standups and tried to understand what was going on.

One of the biggest topics for me was understanding the approach to “how to code” in .NET projects. As a NodeJS programmer, I was not used to patterns like clean architecture and CQRS. Adapting to these and other patterns/principles was a little bit tricky because it required a mental shift.

First contribution

My first pull request was intentionally small. I added some improvements to the local Docker setup.

After this, I started working on my first feature. My approach was to create a PR, even it was 100% wrong, and get feedback from others and iterate.

It perfectly showed that in the engineering world, a pull request is the easiest form of communication.

Total fun

After approximately one month, I started to feel quite confident and guess what? The most experienced engineer on the team began a three-week holiday. At the same time. We kicked off a new project. The timing couldn’t have been more challenging.

I found that I can use skills from my previous job as a tech leader.

• Breaking big problems into smaller ones
• Designing the tech aspects of a project
• Finding the shortest way to prototype/MVP
• Explaining to others how the solution will work

It helped me to start work on the new project as a backend engineer and to cooperate with a frontend developer. I felt we had good progress and what we do makes sense.

Expected-unexpected benefits of a new role

On one hand benefits I describe below are expected, but on the other hand, when I realized them, I felt something like “AHA moment.” I told to myself, “WOW, it’s nice and it's something that I looked for. Why did I not change the job earlier?”

1. Freedom from meetings

Suddenly being an attendee rather than a facilitator was awesome. I hadn’t realized how much my mental energy moderating meetings had consumed.

2. Focus on depth rather than breadth

As a tech leader, I developed broad but shallow knowledge across many areas. When I return to an individual contributor role I could develop deep expertise in specific areas again — something I had missed.

3. 100% technical independence

I felt again that I have 100% influence on how to do something and how to solve the problem I am working on. I like this feeling when I know that solving the case is only a matter of time and going deep enough into the details.

Challanges

The first one was about feeling like a junior. Despite my experience, sometimes it was hard to understand the code, the architecture on a code level, etc. Especially when struggling with framework-specific issues.

I tried to prepare myself and learn some .NET and C# stuff, but the real learning starts when you have to write production-ready code under time pressure.

What can I advise you on when you start a new job?

(The order doesn’t matter; all tips are on the same level)

- Build relationships

Technology is important for engineers, but when you work in a team, People are more important (it’s not obvious for all of us, really).

I got advice that I should take my time and meet people. Actually, it was hard for me, but I spent time talking with people and typically these talks were very interesting!

Build relationships, this is how to onboard perfectly.

- Prioritize code review

I wanted to write some code. I thought I would be able to write code from the first day of work. I didn’t but I spent a lot of time reading others’ code and doing code review. I learned a lot.

Prioritize code review, this is how to onboard perfectly.

- Start small

I wanted to build big things and show how good I am. Nice idea, but a better idea is to start easy. Refactor some code. Improve dev tooling. Fix bugs. From time to time, do more complex things and grow organically.

Start small, this is how to onboard perfectly.

- Be curious

When I saw .Net code, I didn’t understand too much. When you look at something new, you can have the same feeling. You can like something and not like it. And you have two options: complain or be curious. Ask “why?” Go deeper. Ask “why” again and again.

Be curious, this is how to onboard perfectly.

- Be patient

Patience is a useful virtue in both life and coding. People also says that Rush is a bad advisor. You can rush and scrap the production. You can be patient and be sure not to screw up. You can wait for the code review. You can tune in to someone and at least have time to meet. Patience does make sense.

Be patient, this is how to onboard perfectly.

- Be nice

Last but not least (I hate this sentence. Actually, why do I use it here???) Be a nice person. Nobody wants to work with jerks. Be respectful, and think three times before you say something stupid. Listen more than talk.

Be nice, this is how to onboard perfectly.

Conclusion

Onboarding into a new job and role can be demanding. Each of us goes through it individually and has our own needs and challenges.

What is definitely important is our attitude. It is good to use this new beginning as an opportunity to meet new people, learn something different, and look at something familiar from a new perspective. I hope that as you go through your onboarding, you use it in this way.

Published: 03/27/2025 #blog #CareerTransitions #SoftwareEngineering #TechLeadership #ProfessionalDevelopment #OnboardingProcess

1. To code in TDD
2. Caesar cipher works

Let's start from theory

Caesar cipher

The Caesar cipher is one of the earliest and simplest encryption techniques. It was used by Julius Caesar for his private correspondence.

It works by shifting each letter in the plaintext by a fixed number of positions in the alphabet.

Key features:

• Encrypt text using a specified shift value
• Decrypt text using the same shift value
• Preserve case (uppercase/lowercase) during encryption/decryption
• Handle wraparound at alphabet boundaries (Z → A)
• Preserve non-alphabetic characters (spaces, numbers, punctuation)
• Support for negative shift values

How Caesar cipher works

I'll show you how encryption and decryption process works in this cipher.

Encryption process

1. Take each letter in the plaintext message
2. Shift it forward in the alphabet by the specified amount (the key)
3. Wrap around from Z to A if necessary
4. Non-alphabetic characters remain unchanged

Decryption process

1. Take each letter in the encrypted message
2. Shift it backward in the alphabet by the same amount
3. Wrap around from A to Z if necessary
4. Non-alphabetic characters remain unchanged

flowchart TD
    A[Start] --> B[Take each letter]
    B --> C{Is it a letter?}
    C -->|Yes| D[Determine case]
    C -->|No| E[Keep unchanged]
    D -->|Uppercase| F[Shift from 'A']
    D -->|Lowercase| G[Shift from 'a']
    F --> H[Apply shift]
    G --> H
    H --> I[Handle wraparound]
    I --> J[Add to result]
    E --> J
    J --> K{More letters?}
    K -->|Yes| B
    K -->|No| L[End]

Let's code

It's quite simple, isn't it? Good for us, we can implement in quickly!

Step 1: write initial tests

Start by creating a test project and writing failing tests for the simplest behavior:

1. Create the test project structure:

dotnet new xunit -o CesarCipherTests
dotnet add CesarCipherTests/CesarCipherTests.csproj reference CesarCipherLib/CesarCipherLib.csproj

1. Write the first failing test:

using Xunit;
using CesarCipherLib;

namespace CesarCipherTests;

public class CesarCipherTests
{
    [Fact]
    public void When_EncryptingLetterA_WithShiftOf1_ShouldReturnLetterB()
    {
        // Arrange
        var cipher = new CesarCipher();

        // Act
        var result = cipher.Encrypt("A", 1);

        // Assert
        Assert.Equal("B", result);
    }
}

Running this test will fail since the implementation doesn't exist yet.

Step 2: Implement minimal code

Now, implement just enough code to make the test pass:

1. Create the library project and class:

dotnet new classlib -o CesarCipherLib

1. Implement the minimal CesarCipher class:

namespace CesarCipherLib;

public class CesarCipher
{
    public string Encrypt(string text, int shift)
    {
        if (string.IsNullOrEmpty(text))
            return string.Empty;

        if (text == "A" && shift == 1)
            return "B";

        return text;
    }
}

In the very first implementation we need to do something simple to see green tests.

Running the test now should pass.

Step 3: Add more tests and expand implementation

We can go further by adding more tests cases and improve our implementation.

1. Add the next test for incremental functionality:

[Fact]
public void When_EncryptingLetterB_WithShiftOf1_ShouldReturnLetterC()
{
    var cipher = new CesarCipher();
    var result = cipher.Encrypt("B", 1);
    Assert.Equal("C", result);
}

1. Refine the implementation to handle this case:

public string Encrypt(string text, int shift)
{
    if (string.IsNullOrEmpty(text))
        return string.Empty;

    var result = new System.Text.StringBuilder();

    foreach (char c in text)
    {
        if (char.IsUpper(c))
        {
            char shifted = (char)(((c - 'A' + shift) % 26) + 'A');
            result.Append(shifted);
        }
        else
        {
            result.Append(c);
        }
    }

    return result.ToString();
}

Note that this implementation only shifts uppercase letters and leaves all other characters (lowercase letters, numbers, symbols, etc.) unchanged.

1. Add a test for alphabet wraparound:

[Fact]
public void When_EncryptingLetterZ_WithShiftOf1_ShouldReturnLetterA()
{
    var cipher = new CesarCipher();
    var result = cipher.Encrypt("Z", 1);
    Assert.Equal("A", result);
}

1. Continue with tests for lowercase letters:

[Fact]
public void When_EncryptingLowercaseA_WithShiftOf1_ShouldReturnLowercaseB()
{
    var cipher = new CesarCipher();
    var result = cipher.Encrypt("a", 1);
    Assert.Equal("b", result);
}

1. Expand the implementation to handle both cases:

public string Encrypt(string text, int shift)
{
    if (string.IsNullOrEmpty(text))
        return string.Empty;

    var result = new System.Text.StringBuilder();

    foreach (char inputChar in text)
    {
        if (char.IsLetter(inputChar))
        {
            bool isLower = char.IsLower(inputChar);
            char baseChar = isLower ? 'a' : 'A';

            int normalizedChar = (inputChar - baseChar + shift) % 26;
            if (normalizedChar < 0) normalizedChar += 26;

            result.Append((char)(baseChar + normalizedChar));
        }
        else
        {
            result.Append(inputChar);
        }
    }

    return result.ToString();
}

Step 4: Implement decryption

1. Add a test for decryption functionality:

[Fact]
public void When_DecryptingEncryptedText_ShouldReturnOriginalText()
{
    var cipher = new CesarCipher();
    var plainText = "Hello, World!";
    var shift = 5;
    var encryptedText = cipher.Encrypt(plainText, shift);

    var decryptedText = cipher.Decrypt(encryptedText, shift);

    Assert.Equal(plainText, decryptedText);
}

1. Implement the Decrypt method:

public string Decrypt(string text, int shift)
{
    // Decryption is just encryption with the negative shift
    return Encrypt(text, -shift);
}

Step 5: Handle edge cases

1. Add tests for edge cases:

[Fact]
public void When_EncryptingLetterA_WithShiftOfMinus1_ShouldReturnLetterZ()
{
    var cipher = new CesarCipher();
    var result = cipher.Encrypt("A", -1);
    Assert.Equal("Z", result);
}

[Fact]
public void When_EncryptingEmptyString_ShouldReturnEmptyString()
{
    var cipher = new CesarCipher();
    var result = cipher.Encrypt("", 1);
    Assert.Equal("", result);
}

[Fact]
public void When_EncryptingWithShiftOf0_ShouldReturnOriginalText()
{
    var cipher = new CesarCipher();
    var text = "HELLO";
    var result = cipher.Encrypt(text, 0);
    Assert.Equal(text, result);
}

1. Make sure your implementation handles all these cases correctly.

Step 6: Refactor and finalize

1. Review your implementation for any potential improvements while keeping all tests passing.

2. Create a simple console application to demonstrate the functionality:

using CesarCipherLib;

namespace CesarCipherDemo;

public class Program
{
    public static void Main(string[] args)
    {
        Console.WriteLine("=== Caesar Cipher Demo ===");

        var cipher = new CesarCipher();

        // Example usage
        string message = "HELLO WORLD";
        int shift = 3;
        string encrypted = cipher.Encrypt(message, shift);

        Console.WriteLine($"Original: {message}");
        Console.WriteLine($"Encrypted: {encrypted}");
        Console.WriteLine($"Decrypted: {cipher.Decrypt(encrypted, shift)}");
    }
}

Final verification

1. Run the test suite to verify all functionality:

dotnet test CesarCipherTests

1. Run the sample application to demonstrate the cipher in action:

dotnet run

That's all!

Summary

By following this TDD approach, we've created a Caesar Cipher implementation that:

• Preserves letter case
• Handles special characters
• Supports negative shifts
• Properly wraps around the alphabet
• Is thoroughly tested against various edge cases

Links

• https://github.com/Frodigo/garage/blob/main/sandbox/cybersecurity/cryptography/HistoricalCiphersDemo/Ciphers/Caesar/CaesarCipher.cs
• https://github.com/Frodigo/garage/blob/main/sandbox/cybersecurity/cryptography/HistoricalCiphersDemo/Tests/CaesarCipherTests.cs
• https://github.com/Frodigo/garage/tree/main/sandbox/cybersecurity/cryptography/HistoricalCiphersDemo

Published at: 26/03/2025 #blog #ProgrammingFundamentals #Cybersecurity #CSharp #CSharp #xUnit #DotNet #Tutorial #ConceptExplanation #Intermediate #AutomatedTesting

#blog

Eventually, this setup became overly complex, and my enjoyment of blogging declined. I decided to abandon WordPress and migrate my blog to a static site built with the Astro framework. In today’s article, I’ll share the journey I took and explain why Astro is an excellent choice for blogging, especially for programmers and web developers. I’ll also show you how I quickly and automatically imported all my WordPress posts into static Markdown files.

When WordPress Becomes a Burden

WordPress is suitable for 99% o==f== people. It worked for me too, but as I added more plugins, it started running slower and slower.

I used Elementor for customizing my site, but honestly, as a web developer, it’s much easier for me to customize the site’s appearance by editing HTML and CSS rather than using a visual editor.

The growing number of plugins in WordPress negatively impacted the site’s speed for end-users, and I wanted it to be lightning-fast. Plugins also require regular updates. While updates are theoretically automatic, they don’t always work as expected. Once, I updated Elementor, and my site stopped working, costing me several hours of troubleshooting and support calls.

With a large number of posts, the WordPress admin panel became sluggish, and finding anything was a chore. The bilingual setup only made it more cumbersome.

Another factor is that WordPress requires a hosting plan with a database, which incurs costs. In contrast, Astro and Markdown enable a static site, which costs me next to nothing to host. Since I currently earn no income from blogging, eliminating hosting and plugin expenses is a significant advantage.

WordPress also required me to monitor uptime since it’s a dynamically rendered site (server-side rendering). Despite configuring a CDN, there was still occasional downtime.

What finally pushed me to migrate from WordPress to Markdown and Astro was my growing frustration with editing posts in WordPress. It might sound trivial, but the need to log into the panel (requiring an internet connection) started to annoy me. Around that time, I began using Obsidian for note-taking and loved its offline functionality and simple Markdown files. With Obsidian, I can quickly jot something down, which wasn’t the case with WordPress.

The First Attempt at Migration

While using Obsidian, I discovered an intriguing YouTuber named Lazar Nikolov, who demonstrated how to integrate Obsidian with Astro (links to his videos at the end). I had already heard about Astro as a compelling meta-framework for building content-focused websites and apps.

Within a few minutes, I had a proof of concept for a site on Astro with a sample page and my first “Hello World” post. The initial experience was fantastic, but my past experiences taught me to temper my enthusiasm and look for potential weaknesses in the setup.

I had many posts on my blog and worried that I’d need to migrate them manually. Copying the first post from WordPress to Markdown was a nightmare — it required reformatting everything and downloading images separately.

Markdown resonates with me as a programmer. But was that enough of a reason to endure this pain? No.

My blog had around 50 posts in two languages. Some were so outdated that I decided not to migrate them, but I still had about 75 posts to move.

I searched for a WordPress plugin to convert posts to Markdown but couldn’t find anything useful. The thought of manual migration made me want to abandon the process and stick with WordPress.

A Ray of Hope

I kept searching and discovered a tool that converts WordPress-exported XML content into Markdown:

https://github.com/lonekorean/wordpress-export-to-markdown

A huge thanks to the creators of this tool — it likely saved me dozens of hours of tedious work.

All I had to do was export my WordPress content using the native export feature and run npx wordpress-export-to-markdown from the command line. Magic ensued!

The tool generated Markdown files, complete with images, ready for use in my Astro project. I only needed to manually add programming language specifications for code blocks and slightly adjust each post’s properties to match the schema in Astro. Incredible!

Building a New Tech Stack

Come along — I’ll show you the technologies I used for the new implementation.

Markdown

As mentioned, I use Obsidian for notes and store all my knowledge there. Transitioning to Markdown simplifies content creation and development for my blog. Thus, the heart of my tech stack, ladies and gentlemen, is: Markdown.

While WordPress is great for blogging and Notion excels at note-taking, I value simplicity. That’s why I chose Markdown — it works perfectly for both note-taking and blogging.

Rendering and Running the Application

I needed a solution to render my Markdown files. While exploring different frameworks for building blogs, I stumbled upon Astro. Initially, I was skeptical — another framework for building websites? But after some analysis and testing, I can confidently say that it’s a fantastic tool, especially for developers running a blog. Here’s why:

Speed and Performance

Astro renders pages server-side and sends the minimal amount of JavaScript to the browser. This translates to lightning-fast page load times. My blog on Astro loads in an instant.

Flexibility Without Compromise

You can use your favorite tools — React, Vue, or Svelte. Personally, I use Vue for more interactive components, while the rest of the site is pure HTML. Thanks to Astro’s island architecture, JavaScript loads only where needed.

Excellent Content Support

Astro has built-in support for Markdown and MDX. I write posts in Markdown using Obsidian, and it all works out of the box. This allows me to focus on writing without worrying about technical barriers.

SEO Benefits

Static page generation and minimal JavaScript are a foundation for great SEO. My blog on Astro scores high in Lighthouse without any additional optimization efforts.

Multilingual Support

On WordPress, I used the paid WPML plugin for multilingual support. In Astro, I wrote a few lines of code to achieve the same functionality — for free. I implemented the structure so that the base domain serves content in English, while the /pl subdirectory handles Polish content. The folder structure is as follows:

- posts/
 - English posts
 - pl/
 - Polish posts

These are my two simple functions for detecting the language and retrieving static translations:

export function getLangFromUrl(url: URL) {
 const [, lang] = url.pathname.split("/");
 if (lang in ui) return lang as keyof typeof ui;
 return defaultLang;
}

export function useTranslations(lang: keyof typeof ui) {
 return function t(key: keyof (typeof ui)[typeof defaultLang]) {
 return ui[lang][key] || ui[defaultLang];
 };
}

I store translations in a simple file:

"header.openMenu": "Open main menu", // English
"header.openMenu": "Otwórz menu główne", // Polish

These can be easily used in the project:

- -
const lang = getLangFromUrl(Astro.url);
const t = useTranslations(lang);
 - -
<span>{t("header.openMenu")}</span>

This setup works flawlessly — for free. Additionally, I use Astro Islands, so some Vue components are included where needed, and this function integrates seamlessly with them.

On WordPress, WPML translations were not only paid but also offered a mediocre experience. With Astro, I can translate Markdown files entirely using any AI tool, making the process more efficient.

Deployment

In WordPress, deployment was automatic — changes appeared as soon as I saved them in the admin panel.

In my new implementation, the project is built upon pushing changes to the main branch. The built project is deployed as a static site on Vercel. The build process is fast, although I understand it may slow down as content grows — a reasonable trade-off.

Testing

For testing, I used Playwright. Since I don’t have much to test, I’ve only written tests for the newsletter subscription functionality so far. However, even this small step forward feels significant compared to WordPress, where the only testing was manual and on production.

Diagrams

In Obsidian, diagrams work out of the box with Mermaid.js. Integrating Mermaid with Astro was equally straightforward, enabling me to write diagram code that’s automatically rendered as SVGs. I even customized the appearance of these diagrams to match my blog’s theme with just a few lines of configuration and the remark-mermaid plugin:

markdown: {
  remarkPlugins: [
    [
      remarkMermaid,
      {
        mermaidConfig: {
          theme: "dark",
          look: "handDrawn",
          themeCSS: ".flowchart { margin-right: 30px; }",
          themeVariables: {
            fontSize: "18px",
            darkMode: true,
            nodeBorder: "#A130E7",
            mainBkg: "#0a1929",
            nodeTextColor: "#fff",
          },
        },
      },
    ],
  ],
},

Frontend Technologies

Alpine.js vs. Vue.js

Initially, I used Alpine.js for client-side functionality like toggling navigation menus or validating forms. While it worked for simple tasks, I struggled with more complex requirements. Lacking prior experience with Alpine.js, learning it became a chore.

Eventually, I leveraged Astro Islands and switched to Vue.js, a framework I’m highly experienced with, for browser-side functionality.

Tailwind CSS vs. Sass

At first, I styled the app with Tailwind CSS. However, over time, I switched to Sass. Tailwind’s approach to CSS didn’t resonate with me — I prefer separating structure (HTML) from appearance (CSS). This way, I can add CSS classes in HTML and define their properties in the <style> section, making the code more readable for me.

Lessons Learned from the Migration

1. Lightning-Fast Performance

Static sites built with Astro are significantly faster and score higher in PageSpeed Insights. Without additional optimization, my site achieves an 80/100 score on mobile, compared to 30 on WordPress (even after optimizations).

2. Markdown Simplicity

Editing content in Markdown is far easier than in WordPress. Finding and modifying anything is a breeze, especially with tools like VS Code, which allow global search and replace. Even with the additional steps of committing, pushing changes, and waiting for the build, the process feels more efficient than WordPress.

3. Cost Reduction

I no longer pay for hosting, a database, uptime checks, or WordPress plugins. A static site with my level of traffic incurs almost no costs and ensures 100% uptime.

4. Seamless Integration with Obsidian

This new approach tightly integrates my blog with my knowledge and notes stored in Obsidian, making content creation easier and more enjoyable.

5. Unexpected Benefits

With everything in Git, I have a complete history of my work, which motivates me and provides a sense of accomplishment. Additionally, I can work offline and publish whenever I have an internet connection — a blessing for anyone familiar with the reliability of Polish trains.

Challenges

In WordPress, there’s a plugin for everything, whereas in Astro, you often need to implement solutions yourself. Fortunately, most things require a one-time setup.

Collaboration might also be easier on WordPress. If I wanted someone else to contribute content, it would be simpler to find someone familiar with WordPress, as no technical knowledge is required to write there.

Conclusion

In this article, I shared my journey of migrating my blog from WordPress to Astro, and how Markdown simplified my content creation process. I discussed the challenges I faced with WordPress, from slow performance and editing frustrations to hosting and plugin costs. Then, I detailed how I streamlined the migration process with the right tools.

Static sites built with Astro are fast, cost-effective, and provide greater control over content. Integration with Obsidian further enhances the workflow, making it a fantastic option for tech enthusiasts who value simplicity, speed, and flexibility.

If you enjoyed this post, follow me for more articles. I’d love to hear about your experiences and perspectives in the comments!

Links

• https://www.youtube.com/watch?v=33Mk-KrWklU&t=610s
• https://www.youtube.com/watch?v=dz3GOp4hN50&t=357s
• https://github.com/lonekorean/wordpress-export-to-markdown](https://github.com/lonekorean/wordpress-export-to-markdown?tab=readme-ov-file%29
• https://github.com/remcohaszing/remark-mermaidjs
• https://obsidian.md/
• https://astro.build/
• https://playwright.dev/
• https://alpinejs.dev/
• https://marcinkwiatkowski.com/blog

Published: 15/01/2025 #blog #astrojs #WebDevelopment #WordpressAlternatives #obsidian

Of course, you could try to ask about the agenda beforehand, but today I want to focus on such a hopeless case. There’s a meeting, nobody except the organizer knows why this meeting is happening, and the entire development team is there. The meeting is scheduled for 30 minutes.

At the beginning, there’s small talk, of course. I’m not joking here — small talk is important — if there’s no small talk, it means the atmosphere in the team and at the meeting isn’t good.

The 100-Point Question

Then the organizer starts talking about something, usually gives an introduction, and then fires away with questions like:

• I came up with feature FOO, how much time do you need for this?
• Functionality BAR is slow, what can you do to improve it?
• Why might users not notice the value of this feature? How can we change that?
• If we had to cut one thing from the roadmap, what would it be and why
• We need to show this functionality in today’s demo, but it’s not in production yet. Can we quickly finish and show it?

These are questions that aren’t easy to answer, even if you ask questions to clarify the problem.

Answering Under Time Pressure

The problem arises when the questioner expects an immediate answer. I’ve often seen people (or myself) trying to answer such questions under pressure in the shortest possible time.

You can answer intuitively or based on your experience. Then the boss is happy, and the train (project) keeps moving forward.

But what first comes to mind isn’t always the best. You can’t always solve a problem in fifteen minutes. Sometimes you need time to investigate the matter.

Have you ever said something under pressure and later regretted it? I have, and it’s a terrible feeling.

I’ve worked with many engineers, and many of them, especially the ambitious ones, don’t want to admit they don’t know something or don’t want to be blockers and slow things down. Sometimes they’re afraid to speak up for some reason, or in other cases, they don’t want to look bad in front of others.

What If We Gave Ourselves More Time?

Instead of saying whatever comes to mind, simply say “I don’t know”. You can explain why, but just “I don’t know” should be enough in an organization that isn’t broken.

Because you know what? It’s obvious that sometimes you need more time to answer a question. None of us knows everything, and projects are becoming more demanding, and we’re increasingly using new technologies, even ones that didn’t exist a few years ago.

Besides, meetings without agendas, ad hoc meetings are a nightmare. There isn’t even time to prepare because you don’t know what for. When we say “I don’t know”, the questioner might be unhappy, but if you’re a specialist and still don’t know, you need to stand firm until the questioner understands.

A wise boss will understand.

They’ll ask what’s needed to be able to answer the question. They’ll listen to your objections, ask about challenges, start a dialogue.

You’re Not Alone

Remember, even if you don’t know something, your teammate might know and can help you. You work as a team, and each of us should support others. Be a team.

If you’re afraid to say “I don’t know” because you think you’ll delay the project, I’ll tell you that’s total nonsense. Saying something thoughtlessly is worse than saying “I don’t know” and can lead to doing something stupid as a team.

And usually, when we do stupid things mindlessly, we waste more time than if we had said “I don’t know” and taken time for research.

“I Don’t Know” Prevents Mindless Action

When you say “I don’t know”, there’s a chance you’ll have more time to dive into the topic to investigate and find an answer. You’ll say “no” to mindless action, to later say “yes” to work that will bring real value to your project.

Space will appear for doing things that are needed and well-thought-out. Space for discussion will appear.

Collaboration will appear.

A World of Not-Knowing is Better Than a World of Ignorance

Someone who has a ready answer for everything is ignorant. I’m afraid of such people. I’ve seen how such “wise men” destroyed projects with thoughtless decisions. Do you want to be another wise man, or a conscious engineer who thinks about how to really do valuable things and is a long-term partner for business?

If so, then simply don’t be afraid to say “I don’t know” and give yourself time to think. Talk about your objections and doubts. Also try to propose some action, like needing a few days for research and coming back with an answer afterward.

Conclusion

Thanks to “I don’t know”, you’ll have more time to understand the problem and influence your project to be better in the long term.

Not knowing is human. Be curious and you’ll learn.

==Of course, sometimes it’s worth trusting your intuition and experience. But remember that “I don’t know” is an answer you shouldn’t be ashamed of.==

If you liked this article, share it with a colleague and follow me to see more like it.

Published: 07/01/2025 #blog #SoftwareEngineering #Leadership #EngineeringMangement #TeamCollaboration #SelfImprovement

The Good Old Monolith

flowchart LR
    subgraph Monolith
        A[UI] --> B[Single Application]
        B --> C[Single Database]
    end

I've worked with various system architectures for many years and always wonder why some solutions work well in certain organizations but not in others. A monolith, or traditional application architecture, has much in common with a classic car. Simple engine, minimal electronics, everything is well-known and easy to understand. When a gasoline engine in a classic car won't start, it usually comes down to two reasons:

1. no fuel
2. no electricity/spark

(note: I'm greatly simplifying here, but this isn't the place for in-depth analysis of how engines work)

In a monolith, you have one database, one deployment, one team. It's like a car that any mechanic can diagnose and fix. Debugging is simple - everything is in one place. Database transactions work reliably. Deployment is like taking a walk - simple and predictable.

The problem is that this car, like a monolith, has its limitations. No parking sensors, cameras, conveniences or driving assistance systems. You can add all of this yourself, but it's not simple, and the more you change and add non-standard things, the harder the car becomes to maintain. And it's the same with monoliths. Making changes becomes increasingly difficult. Young programmers complain about outdated practices. Scaling requires more and more resources.

The Microservices Revolution

flowchart LR
    subgraph Microservices
        D[UI] --> E[Service 1]
        D --> F[Service 2]
        D --> G[Service 3]
        E --> H[(DB 1)]
        F --> I[(DB 2)]
        G --> J[(DB 3)]
    end

And here come microservices - like the latest cars where the engine and chassis are wrapped in various systems that can work wonders. Microservices offer a vision of a system composed of independent, small services. But this vision, though tempting, raises legitimate concerns.

flowchart TB
    subgraph "Microservice Complexity"
        A[Microservice] --> B[Infrastructure]
        A --> C[Monitoring]
        A --> D[Communication]
        A --> E[Deployment]
        A --> F[Security]
        A --> G[Data consistency]
    end

1. Distribution Complexity

It's like going from a stage where fixing a car required a ratchet, screwdriver and hammer to a point where you can't even begin diagnostics without a range of diagnostic tools and specialist knowledge. Each microservice needs its own infrastructure, monitoring, logging. The world becomes more complicated.

2. Complex Communication

In monoliths, everything was within reach. Now you need a reliable system for inter-service communication. It's like tons of cables in the newest cars. In microservices, you must decide whether to connect via REST API, gRPC, or perhaps opt for distributed communication (events and messages).

3. Data Consistency Challenges

It's like coordinating all driving systems in a modern car to help the driver rather than kill them. When each microservice has its own database, we must ensure information synchronization. A change in one place must be recorded in all necessary places.

The Cost of Transformation

From my personal experience with architectural transformations, I know that each path carries specific costs and risks. While leading a team working on developing a large system that created a platform for e-commerce store owners, I learned that what looks great on paper can be much more complicated in reality.

Approaches to migration

1. Complete System Rewrite

graph TB
    A[Legacy System] -->|"Path 1"| B[Complete Rewrite]
    B --> B1[Advantages]
    B --> B2[Challenges]
    B --> B3[Final: Pure Microservices]

    B1 --> B1A[Latest Tech/Clean Arch/No Debt]
    B2 --> B2A[High Risk/Long Time/Dual Cost]

This path reminds me of my colleague's story, who worked at a company where they wanted to rewrite their entire system from scratch. After several months of work and significant investments, the project was... frozen. Why? There's probably no clear answer, but let's look at the pros and cons of this approach:

Advantages:

• Ability to use the latest technologies
• Clean code without technical debt
• Architecture tailored to current needs

Disadvantages:

• Huge business risk
• Long period without new features
• High costs of parallel development
• Risk of losing business knowledge from the old system

2. Monolith Modernization

I've heard of several successful cases of monolith modernization. The key was focusing on what really needed improvement, rather than blindly following trends.

graph TD
    A[Legacy System] -->|"Path 2"| C[Monolith Modernization]
    C --> C1[Advantages]
    C --> C2[Challenges]
    C --> C3[Final: Enhanced Monolith]

    C1 --> C1A[Lower Cost/Continuity/Knowledge]
    C2 --> C2A[Limited Tech/Scale Issues/Legacy]

Advantages:

• Lower risk - system continues to operate
• Lower initial costs
• Possibility of gradual improvements
• Retention of business knowledge

Disadvantages:

• Technological limitations remain
• Difficulties with fundamental changes
• Scalability problems
• Challenges in recruiting for older technologies

3. Gradual Transformation

This approach worked best in my project. We started by extracting several critical functionalities into separate services while maintaining the working monolith as the system's core.

graph TD
    A[Legacy System] -->|"Path 3"| D[Gradual Transformation]
    D --> D1[Advantages]
    D --> D2[Challenges]
    D --> D3[Final: Hybrid System]

    D1 --> D1A[Controlled Risk/Learning/Flexibility]
    D2 --> D2A[Complex/Slower/Dual Maintenance]

Advantages:

• Controlled risk
• Opportunity to learn from small projects
• Business continuity maintained
• Gradual building of team competencies

Disadvantages:

• Complexity during transition period
• Slower pace of changes
• Complicated integration of old with new
• Greater infrastructure requirements

With this approach, a hybrid architecture works best in the transitional state, where an API Gateway is placed between the frontend and backend services. The API Gateway is responsible for authentication and routing requests to the appropriate services.

flowchart TB
  subgraph "Hybrid Architecture"
    A[Frontend] --> B[API Gateway]
    B --> C[Legacy Monolith]
    B --> D[New Microservice 1]
    B --> E[New Microservice 2]
  end

Practical Insights

After months of working with microservices, I've reached several important conclusions:

1. There are no universal solutions - architecture must fit the specific organization, its culture, and needs.

2. People are more important than technology - the best architecture won't help if the team isn't ready for it.

3. Evolution is better than revolution - gradual changes often bring better results than radical transformations.

4. Business must come first - architecture should support business goals, not be a goal in itself.

5. You need time to learn – creating your first microservice doesn’t mean you already "know microservices." This is only the beginning of your learning journey; everything is still ahead of you.

Summary

The choice between monolith and microservices, as well as the transformation method, are decisions that will have a long-term impact on any organization. The key is finding balance between technological ambitions and business realities.

Remember that neither monoliths nor microservices are inherently bad - everything depends on context. Sometimes the best solution might be a hybrid of both approaches, where part of the system remains a monolith while critical components operate as microservices.

#SoftwareArchitecture #BackendDevelopment #SystemDesign #ConceptExplanation #ArchitectureReview #CaseStudy #Intermediate #Microservices #DataConsistency #SystemIntegration #ArchitecturalTransformation #HybridArchitecture

GraphQL is a query language that allows you to get what you want from the backend, so basically, you need to describe the fields you wish to, write a query, and you are good to go. I have been working a lot with Magento GraphQL API, and I have used the Chrome extension to send requests. The number of queries I have saved has been increasing daily, and I have started looking for something that allows me to organize all my queries and mutations.

Then I remembered the https://www.postman.com/downloads/, which has many beautiful features, and one tiny of them is that you can create your API collection and group all requests you want in folders.

How to export Magento GraphQL schema

The first question I asked myself was how can I export Magento GraphQL schema to the file. After some research, I found a perfect and super easy command-line tool.

The Rover CLI

The Rover CLI created by Apollo allowed me to export Magento Schema. Installation is super easy and took a few seconds (I installed it on Mac, it should be easy on Linux as well).

Use this command to install the Rover CLI:

curl -sSL https://rover.apollo.dev/nix/latest | sh

Then you need to restart a terminal or use this command to configure the rover CLI with the current shell:

exec /bin/zsh -l

Note: this command can be different for your terminal. Please follow the instructions visible in the terminal after the Rover CLI installation.

Export Magento schema to the file

To export GraphQL Magento schema to the file, you can use this command:

rover graph introspect <your_magento_graphql_endpoint>  > <file_name>

Assuming your Magento is available on https://yoursupermagentostore.com, you want to export schema to magento.graphql file, the command you need to use looks like this:

rover graph introspect https://yoursupermagentostore.com > magento.graphql

Import schema to the Postman

Once you export the schema to the file, you can import it into Postman. Open your Postman App, and click the import button

Click "Upload Files"

Select the file that you previously exported using the Rover CLI.

You can optionally enable the option to import deprecated fields. Next, just click Import, and your schema should be imported.

You should see queries and mutations imported:

let's take a look at one of query: route

I marked some areas in the screenshots with the red square.

1. Here you have a URL for the request. It is bound to a variable. In next step I will show you where you can add this variable

2. This is a query body

3. In this area, you can add/modify query variables

How to set variables in Postman

You can see variables in two ways:

1. By filling variable in Collection's settings

2. By creating environment

This time, let's use the first option:

If you set up a URL to Magento correctly, a request should be sent to Magento:

Bonus: how to disable GraphQL schema introspecting in Magento

To be honest GraphQL API intersection enabled by default has danger in terms of security because it's possible to show a GraphQL schema of any Magento shop and use it for shameful acts such as attacks on the store, data theft, etc.

Fortunately, there is an easy way to disable introspection by configuration in Magento.

To do so, please add this entry to your app/etc/env.php file:

'graphql' => [
    'disable_introspection' => true
]

Summary

In this short article, I showed you how to export Magento GraphQL schema and import it to Postman. On the other hand, remember that it is recommended to disable API introspection in Magento for any store on production.

#WebDevelopment #BackendDevelopment #JavaScript #PHP #GraphQL #REST #Magento #Apollo #Postman #Tutorial #QuickTip #BestPractices #Intermediate #APISecurity

Hexagonal architecture, also known as octagonal architecture or ports and adapters architecture, is an approach to software design in which business logic is isolated from the technical layer.

In hexagonal architecture, the application consists of three main parts:

1. Ports - interfaces that define how the application communicates with the external environment. Ports are entry and exit points of the application through which information flows.

2. Adapters - implementations of ports that enable communication between the application and the external environment. Adapters translate information from a format understandable by the external system to a format understandable by the application and vice versa.

3. Business logic - the central part of the application that processes information passed by ports and adapters. Business logic is isolated from implementation details, which enables easy interchangeability of adapters and ports without changes to the business logic.

Ports

Separating business logic from infrastructure components is the main task of the hexagonal architecture. In the business logic layer, instead of directly accessing infrastructure components, you define "ports" as doors for lower-level components.

Think of these ports as USB ports. They are a socket into which you can plug something. You can plug a method for saving data into a database or save data to a file. The business logic doesn't care where the data is saved. It sends the data to the port, and what happens to the data next depends on what is "plugged" into that port.

Adapters

An adapter is exactly what you want to plug into a port. Based on the example above, in which the business logic wants to save data, we can define such a port:

interface Writer {
 saveData(data: string): boolean
}

You can see an interface that contains the saveData function, which takes a string argument named data and returns true or false.

Now, let's take a look at some possible adapters for this port:

const databaseWriter: Writer = {
    saveData: (data: string): boolean => {
        console.log(`"${data}" is saved in the database...`);

        return true;
    }
}

const fileWriter: Writer = {
    saveData: (data: string): boolean => {
        console.log(`"${data}" is saved in the file...`);

        return true;
    }
}

Now you are defining a class that has quite an enigmatic name for the purposes of this example: BusinessLogic:

class BussinesLogic {
    constructor(
        private writer: Writer
    ) {}

    execute(): void {
        this.writer.saveData('my data');
    }
}

The class expects to receive a Writer as an argument. In this simple example, the execute method saves the data and doesn’t care where Writer will save it.

Now, having defined two different adapters, you can use them as shown below:

const app1 = new BussinesLogic(fileWriter);
app1.execute(); // "my data" is saved in the file..."

const app2 = new BussinesLogic(databaseWriter);
app2.execute(); // "my data" is saved in the database..."

Does this make sense?

Now let's look at a more complex example where you are creating a product page for an online store. You have the following use cases:

1. As a user, I can view information about the product and its price.

2. As a user, I can add the product to my cart.

Let's start by defining the types and interfaces for the three entities we need:

type Price = {
    currency: string;
    amount: number;
}

interface Product {
    id: string
    getDescription(): string|null
    getPrice(): Price|null
}

interface Cart {
    addToCart(productId: string): void
}

Here we have the price, product, and cart. I said it would be a bit more complicated example and I think it is. :)

Now see what concrete implementation of the business logic can look like:

class CommerceBussinesLogic {
    constructor(
        private product: Product,
        private cart: Cart
    ) {}

    execute(): void {
        this.product.getDescription();
        this.product.getPrice()
    }

    public addProductToCart(productId: string) {
        return this.cart.addToCart(productId);
    }
}

Business logic exposes two ports: product and cart. Now, let's write adapters for these ports. The client says that they want to integrate with the Magento eCommerce system. They say and have:

class MagentoProductAdapter implements Product {

    private description: string|null = null;
    public price: Price|null = null;

    constructor(
        public id: string
    ) {
        console.log('Imagine that you fetch product data from ecommerce here...') // ex. fetch('<ecommerce_api_url>/product/{id}')
        this.price = {
            amount: 199.00,
            currency: 'EUR'
        }
        this.description = 'Lorem ipsum dolor sit amet';
    }

    public getDescription() {
        return this.description;
    }

     public getPrice() {
        return this.price;
    }
}

class MagentoCartAdapter implements Cart {
        private items: Array<Product>
        private subtotal: Price

    constructor() {
        console.log('Imagine that you fetch cart here ...') // ex. fetch('<ecommerce_api_url>/cart')
        this.items = []
        this.subtotal = {
            amount: 0,
            currency: 'EUR'
        }
    }

     public addToCart(productId: string) {
        console.log('addToCart clicked') // send request to eccommerce here
    }
}

By the way, these examples are very simple pseudo-code in TypeScript, more to show you the idea than to provide production-ready code, so if you see something like this:

console.log("Imagine that you fetch cart here ..."); // ex. fetch('<ecommerce_api_url>/cart')

Now, close your eyes briefly and imagine that this code sends a request to an eCommerce system and retrieves real data. My code doesn't have imagination, so I had to hardcode some data there.

this.items = [];
this.subtotal = {
  amount: 0,
  currency: "EUR",
};

Anyway - the above adapters retrieve code from eCommerce. In this case, it is Magento. See how this code can be executed:

const myProductid = "123";
const myCommerce = new CommerceBussinesLogic(
  new MagentoProductAdapter(myProductid),
  new MagentoCartAdapter(),
);

myCommerce.execute();
// imagine that a user clicks add to cart button...
myCommerce.addProductToCart(myProductid);

The console prints something like this:

[LOG]: "Imagine that you fetch product data from ecommerce here..."
[LOG]: "Imagine that you fetch cart here ..."
[LOG]: "addToCart clicked"

Well done, we have just written the code in Ports and Adapters architecture!

That's not all. Now imagine that after three months it turns out that your client is emotionally unstable and has decided that he want to integrate with the BigCommerce system. The business logic remains the same. What do you do?

You add adapters for BigCommerce:

class BigCommerceProductAdapter implements Product {

    private description: string|null = null;
    public price: Price|null = null;

    constructor(
        public id: string
    ) {
        console.log('Imagine that you fetch product data from BigCommerce here...') // ex. fetch('<ecommerce_api_url>/product/{id}')
        this.price = {
            amount: 199.00,
            currency: 'EUR'
        }
        this.description = 'Lorem ipsum dolor sit amet';
    }

    public getDescription() {
        return this.description;
    }

     public getPrice() {
        return this.price;
    }
}

class BigCommerceCartAdapter implements Cart {
        private items: Array<Product>
        private subtotal: Price

    constructor() {
        console.log('Imagine that you fetch cart from BigCommerce here ...') // ex. fetch('<ecommerce_api_url>/cart')
        this.items = []
        this.subtotal = {
            amount: 0,
            currency: 'EUR'
        }
    }

     public addToCart(productId: string) {
        console.log('addToCart Bigcommerce clicked') // send request to eccommerce here
    }
}

And you push them into your ports:

const bigCommerce = new CommerceBussinesLogic(
  new BigCommerceProductAdapter(myProductid),
  new BigCommerceCartAdapter(),
);

bigCommerce.execute();
// imagine that a user clicks add to cart button...
bigCommerce.addProductToCart(myProductid);

Console says:

[LOG]: "Imagine that you fetch product data from BigCommerce here..."
[LOG]: "Imagine that you fetch cart from BigCommerce here ..."
[LOG]: "addToCart Bigcommerce clicked"

Infrastructure

In hexagonal architecture, the presentation layer and data access layer integrate with external components such as:

• Database

• UI

• External provider

• Message bus

Driving side

The mobile application user interface code or user interface (UI) code of a web application initiates interaction with the application. User data from the UI is supported by the adapter and sent to the business logic through the port.

Driven side

Even databases and external services need an application to function. In this case, the application calls an external service or sends a request to the database. Then, the adapter implements the port to be used.

Dependency inversion principle

Dependency Inversion Principle states that high-level modules that implement business logic should not depend on low-level modules. This means that interfaces should be defined by high-level modules. This makes the system more flexible and easier to modify, because changes made in one module will not affect the other modules, as long as the interfaces remain unchanged.

In the layered architecture, it's exactly the opposite - higher-level modules and, frankly speaking, the core business logic that depends on lower-level modules.

The business logic is not mixed with implementation details or technological problems by inverting the dependencies.

Hexagonal architecture - benefits

• Easy scalability

• Application development

• Easy integration with other systems

• Isolation of business logic from the technical layer, making it easier to introduce changes without affecting the entire system

Hexagonal architecture - drawbacks

• Increased complexity - hexagonal architecture adds components that act as intermediaries, which affects complexity

• Debugging - applications created using the hexagonal architecture pattern may be more difficult to debug because they do not directly use specific implementations.

• Translation - when the business domain is modeled independently of the database or other technology, translation between the models used for persistence or communication and the domain model can be inconvenient. This problem is exacerbated when the models differ significantly from each other both technically and conceptually.

• Learning curve - Hexagonal architecture differs from traditional architectural patterns, which are often imposed on developers by frameworks. This can be more difficult for new programmers due to the need for mediation, translation, and design patterns.

When to use hexagonal architecture?

The correct answer is probably as always: it depends.

If you are building a simple CRUD application, it's probably not worth getting into ports and adapters.

The ports and adapters architecture is more suitable for complex business logic than the layered architecture.

It is worth considering the hexagonal architecture when using different external systems, frameworks, and data reading and writing methods.

You can also consider implementing only some aspects of the architecture to improve problem separation. There are many ways to do this, and it's something to discuss with your team of developers, as each project's answer may differ.

Hexagonal Architecture and DDD (Domain Driven Design)

Hexagonal Architecture and Domain Driven Design (DDD) are two complementary approaches to software design that aim to facilitate flexibility, scalability, and ease of maintenance of various software applications and systems.

Both approaches emphasize the importance of separating business logic from the technical layer and both use interfaces to define how different parts of the system communicate with each other.

In DDD, the goal is to create a clear and consistent model of the business domain and use it to design the software system.

Hexagonal architecture allows for the introduction of this model in a flexible and scalable way, by separating business logic from implementation details and providing transparent communication interfaces.

By combining the principles of hexagonal architecture with DDD modeling techniques, it is possible to create software systems that are both flexible and easy to maintain, and perfectly tailored to the needs of the client.

However, it is important to remember that both approaches require careful planning and design, and may not be suitable for all software projects.

Summary

Hexagonal architecture, also known as ports and adapters, is an architectural pattern that separates business logic from the technical layer and facilitates the introduction of changes without affecting the entire system.

In this pattern, the business logic exposes ports, whose implementation depends on adapters written for specific technologies. In this way, each layer is separated and can be developed independently.

Hexagonal architecture is particularly useful in complex projects that require integration with various external systems, such as databases, UI, external providers, and message buses.

The disadvantages of this architecture are increased complexity, difficulties in debugging, translation, and learning curve.

It is worth considering using hexagonal architecture in projects that require separating the business layer from implementation details and easy integration with various external systems.

You can also combine the principles of hexagonal architecture with DDD modeling techniques to create flexible, easy-to-maintain software systems that are perfectly tailored to the client's needs.

Sources

https://www.goodreads.com/book/show/179133.Domain_Driven_Design

https://www.goodreads.com/book/show/57573212-learning-domain-driven-design

#ProgrammingFundamentals #SoftwareArchitecture #TypeScript #JavaScript #ConceptExplanation #ArchitectureReview #DeepDive #Intermediate #Microservices #Scalability

Recently I described the basics of Magento GraphQL. This time I want to show you a practical example of how to scaffold a headless app connected with Magento GraphQL and fetch appropriate data from Magento based on a given URL. This article is about:

• concept/idea of how to create routing in a custom Magento headless project

• which GraphQL is appropriate to resolve URLs

• how to fetch information about categories, products, and CMS pages from API based on a given URL

• how to implement the URL resolving functionality in the frontend app (in the big picture)

Magento GraphQL routing concept

Let me explain the idea of routing in a headless app from not the best pattern I have already seen. Typically in an eCommerce app, you have the following pages: home/cms pages, category page, product page, my account, checkout, etc.

So you can create some custom routes in a headless app to handle all of them, for example:

• Home - baseUrl/ - to handle homepage

• Page - baseUrl/:pageId - to handle CMS pages

• Category - baseUrl/category/:categoryId

• Product - baseUrl/product/:productId

• Checkout - baseUrl/checkout

• My account - baseUrl/account

That solution works, but the huge disadvantage is that the URLs are not (user and SEO) friendly. In Magento Luma (Monolith version), you can visit pages like in following links:

• https://magento2demo.frodigo.com/women.html - category page

• https://magento2demo.frodigo.com/joust-duffle-bag.html - product page

• https://magento2demo.frodigo.com/about-us - CMS page

The route query

Fortunately, Magento GraphQL supports URL resolving for the category, product, and CMS pages. There is the route query that receives the URL key and returns information about the entity that matches the given URL key or null if it's not possible to resolve the URL.

query resolveRoute($url: String!) {
  route(url: $url) {
    redirect_code,
    relative_url,
    type
    ... on SimpleProduct {
      sku
      url_key
      uid
      type
      name
    }
    ... on CategoryTree {
      name
      product_count
      uid
    }
    ... on CmsPage {
      identifier
      content_heading
      content
    }
  }
}

Complete documentation about the route query: https://devdocs.magento.com/guides/v2.4/graphql/queries/route.html

The route query returns three fields:

• redirect_code (Int) - Contains 0 when there is no redirect error. A value of 301 indicates the URL of the requested resource has been changed permanently, while a value of 302 indicates a temporary redirect.

• relative_url (String) - The relative internal URL. If the specified URL is a redirect, the query returns the redirected URL, not the original

• type (UrlRewriteEntityTypeEnum) - One of PRODUCT, CATEGORY, or CMS_PAGE

The route query has one obligatory parameter: "URL," which is a string.

Moreover, the route query is implemented by SimpleProduct, DownloadableProduct, BundleProduct, GroupedProduct, VirtualProduct, ConfigurableProduct, CategoryTree, and CmsPaage so that you can get information about those entities in the route query. In the example above, I used SimpleProduct, CmsPage, and CategoryTree.

Types of pages in Magento

Three types of URLs can be resolved using Magento GraphQL API and the route query.

CMS

CMS pages contain content like about us, homepage, privacy policy, etc.

Take a look at an example response for the About us page:

// variables:
{
   "url": "about-us"
}

// results:
{
  "data": {
    "route": {
      "redirect_code": 0,
      "relative_url": "about-us",
      "type": "CMS_PAGE",
      "identifier": "about-us",
      "content_heading": "About us",
      "content": "<div class=\"about-info cms-content\">\n      <p class=\"cms-content-important\">With more than 230 stores spanning 43 states and growing, Luma is a nationally recognized active wear manufacturer and retailer. We’re passionate about active lifestyles – and it goes way beyond apparel.</p>\n\n      <p>At Luma, wellness is a way of life. We don’t believe age, gender or past actions define you, only your ambition and desire for wholeness... today.</p>\n\n      <p>We differentiate ourselves through a combination of unique designs and styles merged with unequaled standards of quality and authenticity. Our founders have deep roots in yoga and health communities and our selections serve amateur practitioners and professional athletes alike.</p>\n\n      <ul style=\"list-style: none; margin-top: 20px; padding: 0;\">\n          <li><a href=\"https://magento2demo.frodigo.com/contact/\">Contact Luma</a></li>\n          <li><a href=\"https://magento2demo.frodigo.com/customer-service/\">Customer Service</a></li>\n          <li><a href=\"https://magento2demo.frodigo.com/privacy-policy/\">Luma Privacy Policy</a></li>\n          <li><a href=\"https://magento2demo.frodigo.com/\">Shop Luma</a></li>\n      </ul>\n  </div>\n"
    }
  }
}

The following query that received the "about-us" URL returns type equals CMS_PAGE and information about the CMS page that we wanted to fetch

Product

Product pages present information about products. Take a look at the example "Joust Duffle Bag" product that has the "joust-duffle-bag.html" URL key:

// variables:
{
   "url": "joust-duffle-bag.html"
}

// results:
{
  "data": {
    "route": {
      "redirect_code": 0,
      "relative_url": "joust-duffle-bag.html",
      "type": "PRODUCT",
      "sku": "24-MB01",
      "url_key": "joust-duffle-bag",
      "uid": "MQ==",
      "name": "Joust Duffle Bag"
    }
  }
}

The following query that received the "joust-duffle-bag.html" URL returns type equals PRODUCT and information about the product we wanted to fetch.

Category

Category pages display information about the category. Moreover, Magento has a pretty nice feature called Category Landing Pages that allows rendering CMS blocks (you can display any CMS content on the category page).

Take a look at examples for the women category.

// variables:
{
  "url": "women.html"
}

// results:
{
  "data": {
    "route": {
      "redirect_code": 0,
      "relative_url": "women.html",
      "type": "CATEGORY",
      "name": "Women",
      "product_count": 0,
      "uid": "MjA="
    }
  }
}

When passing the 'women.html' URL, Magento returns the type equals CATEGORY and information about the category that we wanted to fetch

No route

When you pass an URL that doesn't exist in Magento, the route query will return null. Take a look at the example:

// query:
query resolveRoute($url: String!) {
  route(url: $url) {
    redirect_code,
    relative_url,
    type
  }
}

// variables:
{
  "url": "this-is-not-exist-i-am-sure"
}

// results:
{
  "data": {
    "route": null
  }
}

Once you know that the URL doesn't have corresponding information in the Magento backend, you can render the 404 page.

Other routes

Of course, there are more types of pages in eCommerce stores, like checkout pages or customer account pages, but the three types I mentioned before are crucial in terms of SEO and how they are rendered, and what URL is used.

Deprecated URL resolver query

Note there is the urlResolver https://marcin-kwiatkowski.com/blog/graphql/the-full-stack-guide-to-the-graphql-query that basically does the same as the route query, but it's deprecated and should not be used.

Sample implementation in a headless app

Today I want to show some pseudo-code and an idea in the big picture of how to implement URL resolving logic in a NextJS app.

Basically, for those three types of pages that can be resolved (category, product, and CMS), you can create a dynamic route in the pages directory: [[...slug]]. You can create separate routes for other pages like checkout, cart, and my-account. So your pages directory can look like this:

• pages/ [[...slug]].tsx

• pages/checkout.tsx

• pages/cart.tsx

• pages/account.tsx

That's it. All dynamic routes like category, product, and CMS will be handled by [[...slug]] route, and other pages will be operated by custom routes like the cart.tsx or account.tsx

Take a look at the pseudo-code implementation for the [[...slug]] route:

import React, { Suspense } from 'react'
/** Route GraphQL Magento type: **/
import type { Route } from '../types/magento'

/**
 * helper to fetch data on server side
 * signature: function useData<Type>(key, fetcher): ApiData<Type>
 * returns:
 * interface ApiData<Type> {
 *   data: Type,
 *   error: Error
 * }
 */
import useData from '../lib/use-data';
/**
 * Wrapper for GraphQL function that allows to query GraphQL API
 * async <TYPE, VARIABLES>(query, variables = null): Promise<TYPE>
 */
import { query as apiQuery } from '../providers/Api';
/**
 * Route GraphQL queury:
 */
import routeQuery from "../queries/route.gql";
import Loader from "../components/Loader"; // Loaded component
import CmsPage from "../modules/cms/components/CmsPage/CmsPage.server"; // CMS Page component
import ProductPage from "../modules/product/components/ProductPage/ProductPage.server"; // Product Page component
import CategoryPage from "../modules/category/components/CategoryPage/CategoryPage.server"; // Category Page component

type RouteQuery = {
    route: Route
}

/**
 * Enum that represent three possible types of pages
 */
enum PageTypes {
    Product = 'PRODUCT',
    Category = 'CATEGORY',
    CmsPage = 'CMS_PAGE'
}

/**
 * render page content based on given type and url key
 */
const renderPageContent = (route: Route) => {
    const pages = {
        [PageTypes.CmsPage]: <CmsPage data={route}/>,
        [PageTypes.Product]: <ProductPage data={route}/>,
        [PageTypes.Category]: <CategoryPage data={route}/>,

    }

    return pages[route.type]
}

export default function slug({ router }) {
    const { query } = router;
    const slug = query?.slug ? query?.slug?.join('/') : 'home'; // handle dynamic slugs

    /**
     * Fetch route information based on slug
     */
    const { data: { route }} = useData(
        `route/${slug}`,
        () => apiQuery<RouteQuery, { url: string }>(routeQuery, { url: slug }))

    /**
     * content to render:
     */
    const content = renderPageContent(route);

    if (content === null) {
        // redirect to 404 page
    }

    return <Suspense fallback={<Loader/>}>
        {content}
    </Suspense>
}

I hope that the comments in the code are helpful. Besides explaining that code, I would say I use React Server Components (experimental). RSC allows the rendering of React components on the server-side. Because of that, components there has a `.server` prefix. Server components are game-changers in frontend development, and I can't wait where they will be released as stable features!

Moreover, I use TypeScript to that code for a better developer experience. The last thing that deserves to mention is the render page content function that receives the route data and renders an appropriate component.

It's possible to do the same using the switch statement, but I wanted to do that more declaratively.

In the GraphQL examples above, I showed you how to fetch product details, category data, and CMS pages. Components rendered by renderPageContent are perfect places to display that information. They receive the data as a prop, and then its responsibility is to say information on the screen.

Conclusion

This article showed you basic concepts about routing in headless apps connected with Magento GraphQL API.

There is the route query that resolves the URL and returns one of three page types: CMS_PAGE, Category, and Product. You can render those pages using one dynamic route on the front-end side.

You can create static routes for other pages like checkout or my account add implementation.

Thanks to state-of-the-art features like React Server Components, you can do all of that on the server-side, so the performance of a page will be outstanding.

#WebDevelopment #BackendDevelopment #FrontendDevelopment #JavaScript #TypeScript #GraphQL #React #NextJS #Magento #ConceptExplanation #Tutorial #DeepDive #Intermediate #API #Routing #Headless #SEO

First, we need to set up our local PWA Studio instance.

yarn create @magento/pwa

It would be best if you answered some questions on the console.

Then please generate a unique, secure, custom domain for your new project.

cd <PWA Studio root directory>>
yarn run buildpack create-custom-origin .

Scaffolding extension

For development, I recommend creating a module in the pwa-studio-root/src directory and linking it as symlinks in package.json.

cd src/
yarn create @larsroettig/pwa-extension

Again, you will have to answer a few questions.

Now we need to link our module in the package.json file. Please add this entry as a dependency:

"@marcinkwiatkowski/account-information": "link:<absolute_path_to_module"

Now we need to install our module and run the PWA Studio instance.

yarn install
yarn run watch

Before we start development, we should do four things:

• add @magento/venia-ui as a peer dependency

• add @magento/peregrine as a peer dependency

• run the yarn install command in our module directory

• drink coffee, water, or whatever you like

A few words about the extension

Today we will create an account information page where Customers will find the necessary information about themselves.

Requirements

1. The Page should be visible at the ‘base_url/account-information’ URL

   1. the Page should be visible only for logged-in customers
   2. the Customer’s first name and last name will be displayed on the Page.

2. A link to the Page should be visible in the customer menu

Adding a new route

Now it’s time to coding!

Defining the route

Thanks to targets, we can add a new route to PWA Studio in an easy way. Please add the following content to the intercept.js file:

targets.of("@magento/venia-ui").routes.tap((routes) => {
  routes.push({
    name: "AccountInformation",
    pattern: "/account-information",
    path: require.resolve(
      "@marcinkwiatkowski/account-information/src/lib/components/AccountInformation/",
    ),
  });
  return routes;
});

As you can see on line 6, we defined the component which will be rendered when the user opens the Page.

Adding AccountInformation component

To start, please create a straightforward React component:

import React from "react";

const AccountInformation = () => {
  return (
    <div>
      <h1>Hello world</h1>
    </div>
  );
};

export default AccountInformation;

Remember to add an index.js file, which exports the component

Adding customer data

We need to have three pieces of information about the Customer:

1. Is the Customer signed in?

2. First name

3. Last name

We are going to create the hook which will use the useUserContext talon. Please create a file at src / lib / talons / AccountInformation / useAccountInformation.js with the following content:

import { useUserContext } from "@magento/peregrine/lib/context/user";

/**
 * useAccountInformation hook which provides data for AccountInformation component
 * @returns {{currentUser: {id, email, firstname, lastname, is_subscribed}, isSignedIn: boolean}}
 */
export const useAccountInformation = () => {
  const [{ currentUser, isSignedIn }] = useUserContext();

  return {
    currentUser,
    isSignedIn,
  };
};

Display information about Customer on the Page

To display the Customer’s information, we have to import the hook and add JSX Markup to the component:

import React from "react";
import { useAccountInformation } from "../../talons/AccountInformation/useAccountInformation";

const AccountInformation = () => {
  const { currentUser, isSignedIn } = useAccountInformation();

  return (
    <div>
      <h1>Account information</h1>

      <ul>
        <li>
          <strong>First name: </strong>
          <span>{currentUser.firstname}</span>
        </li>
        <li>
          <strong>Last name: </strong>
          <span>{currentUser.lastname}</span>
        </li>
      </ul>
    </div>
  );
};

export default AccountInformation;

Adding styles

The next thing which we do is to add styles for our component. Please create the accountInformation.css file in the component directory:

.root {
  display: grid;
  padding: 2.5rem 3rem;
  row-gap: 2rem;
}

.title {
  justify-self: center;
  font-family: var(--venia-global-fontFamily-serif);
  font-weight: var(--venia-global-fontWeight-bold);
}

.list {
  justify-self: center;
  margin: 15px auto;
  text-align: center;
}

Then you can import these styles as a module component and use them.

import React from "react";
import { useAccountInformation } from "../../talons/AccountInformation/useAccountInformation";
import { mergeClasses } from "@magento/venia-ui/lib/classify";
import defaultClasses from "./accountInformation.css";

const AccountInformation = (props) => {
  const classes = mergeClasses(defaultClasses, props.classes);
  const { currentUser, isSignedIn } = useAccountInformation();

  return (
    <div className={classes.root}>
      <h1 className={classes.title}>Account information</h1>

      <ul className={classes.list}>
        <li>
          <strong>First name: </strong>
          <span>{currentUser.firstname}</span>
        </li>
        <li>
          <strong>Last name: </strong>
          <span>{currentUser.lastname}</span>
        </li>
      </ul>
    </div>
  );
};

export default AccountInformation;

Checking if the Customer is logged in

We want to redirect to the homepage when the Customer is not logged in. To achieve this, we are going to use the @magento/venia-drivers Redirect component.

import React from "react";
import { useAccountInformation } from "../../talons/AccountInformation/useAccountInformation";
import { Redirect } from "@magento/venia-ui/lib/drivers";
import { mergeClasses } from "@magento/venia-ui/lib/classify";
import defaultClasses from "./accountInformation.css";

const AccountInformation = (props) => {
  const classes = mergeClasses(defaultClasses, props.classes);
  const { currentUser, isSignedIn } = useAccountInformation();

  if (!isSignedIn) {
    return <Redirect to="/" />;
  }

  return (
    <div className={classes.root}>
      <h1 className={classes.title}>Account information</h1>

      <ul className={classes.list}>
        <li>
          <strong>First name: </strong>
          <span>{currentUser.firstname}</span>
        </li>
        <li>
          <strong>Last name: </strong>
          <span>{currentUser.lastname}</span>
        </li>
      </ul>
    </div>
  );
};

export default AccountInformation;

Adding a link to the customer menu

The Page looks good, but Customers need to know that this Page exists, so we will add a \ link to the customer menu. If the user clicks the link, PWA Studio will redirect to the account-information Page.

Note: I’m using overwrites here to extend the VeniaUI component and overwrite talon, but in the next version of PWA Studio, there will be a better way to extend talons using a new called Targetables.

Overwriting components

Create the file lib / components / AccountMenu / accountMenuItems.js

import React from "react";
import { func, shape, string } from "prop-types";
import { FormattedMessage } from "react-intl";

import { Link } from "@magento/venia-drivers";
import { mergeClasses } from "@magento/venia-ui/lib/classify";
import { useAccountMenuItems } from "../../talons/AccountMenu/useAccountMenuItems";

import defaultClasses from "@magento/venia-ui/lib/components/AccountMenu/accountMenuItems.css";

const AccountMenuItems = (props) => {
  const { onSignOut } = props;

  const talonProps = useAccountMenuItems({ onSignOut });
  const { handleSignOut, menuItems } = talonProps;

  const classes = mergeClasses(defaultClasses, props.classes);

  const menu = menuItems.map((item) => {
    return (
      <Link className={classes.link} key={item.name} to={item.url}>
        <FormattedMessage id={item.id} />
      </Link>
    );
  });

  return (
    <div className={classes.root}>
      {menu}
      <button className={classes.signOut} onClick={handleSignOut} type="button">
        <FormattedMessage id={`Sign Out`} />
      </button>
    </div>
  );
};

export default AccountMenuItems;

AccountMenuItems.propTypes = {
  classes: shape({
    link: string,
    signOut: string,
  }),
  onSignOut: func,
};

The most important thing here is line 7 where we change the path to the useAccountMenuItems talons.

The next thing we need is the lib / talons / AccountInformation / useAccountInformation.js talon.

import { useCallback } from "react";

/**
 * @param {Object}      props
 * @param {Function}    props.onSignOut - A function to call when sign out occurs.
 *
 * @returns {Object}    result
 * @returns {Function}  result.handleSignOut - The function to handle sign out actions.
 */
export const useAccountMenuItems = (props) => {
  const { onSignOut } = props;

  const handleSignOut = useCallback(() => {
    onSignOut();
  }, [onSignOut]);

  const MENU_ITEMS = [
    {
      name: "Communications",
      id: "accountMenu.communicationsLink",
      url: "/communications",
    },
    {
      name: "Account Information",
      id: "accountMenu.accountInfoLink",
      url: "/account-information",
    },
  ];

  return {
    handleSignOut,
    menuItems: MENU_ITEMS,
  };
};

The last thing is to add moduleOverrideebpackPlugin, add a mapping, and modify the intercept.js file.

I’ll let you handle this one!

If you do it correctly, you will see a link to the Page in the menu:

Unit tests

Thanks to the generator, we have already configured the environment for unit tests. We can use the Jest Testing Framework.

Please add a src / lib / components / AccountInformation / __tests__/ AccountInformation.spec.js file with the following content:

import React from "react";
import { default as createTestInstance } from "@magento/peregrine/lib/util/createTestInstance";
import { useAccountInformation } from "../../../talons/AccountInformation/useAccountInformation";
import AccountInformation from "../AccountInformation";

jest.mock(
  "@marcinkwiatkowski/customer-menu/src/lib/talons/AccountInformation/useAccountInformation",
);
jest.mock("@magento/venia-ui/lib/classify");
jest.mock("@magento/peregrine/lib/context/user", () => {
  const userState = {
    isGettingDetails: false,
    getDetailsError: null,
  };
  const userApi = {
    getUserDetails: jest.fn(),
    setToken: jest.fn(),
    signIn: jest.fn(),
  };
  const useUserContext = jest.fn(() => [userState, userApi]);

  return { useUserContext };
});

jest.mock("@magento/venia-ui/lib/drivers", () => ({
  Redirect: (props) => <mock-Redirect {...props} />,
}));

test("Redirects when not authenticated", () => {
  useAccountInformation.mockReturnValue({
    isSignedIn: false,
    currentUser: null,
  });

  const tree = createTestInstance(<AccountInformation />);
  expect(tree.toJSON()).toMatchSnapshot();
});

test("Display page when user is signed in", () => {
  useAccountInformation.mockReturnValue({
    isSignedIn: true,
    currentUser: {
      firstname: "Marcin",
      lastname: "Kwiatkowski",
    },
  });

  const tree = createTestInstance(<AccountInformation />);
  expect(tree.toJSON()).toMatchSnapshot();
});

Running tests

If you want to run a test, just run this command:

yarn run test

The results should look like this:

Other generator features

The generator has a few other features which help you to create excellent quality components.

Linting

ESLint checks all JavaScript code. You can run this linter manually using this command:

yarn run lint

Configuration for esLint is in the .eslintrc.js file.

Code formatting

Also, you can automatically format your code by running this command:

yarn run format

Husky

Thanks to Husky, these commands (lint and format) run automatically before each git commit.

Source code

You can find the source code of the extension which we just made on my https://github.com/Frodigo/pwa-studio-extension-example

Summary

As you can see, thanks to PWA Studio Extension Generator, you can start developing your extension quickly, and you don’t have to worry about configuring things from scratch. You can grab base files and configs and change whatever you want. Happy Hacking!

#WebDevelopment #FrontendDevelopment #ProgrammingFundamentals #JavaScript #CSS #Bash #React #PWAStudio #Jest #Yarn #GraphQL #Tutorial #ProjectSetup #BestPractices #Intermediate #Testing

Spoiler alert: there will even be a third series, but to the point!

So since we know the basics of Vue, we now have to dig into the Vue platform to create a custom component. We first create a component representing every player in our football (soccer??) team. We learn several basic concepts throughout the process, like calling components within another component, sending the data to the component via props, or using a provide/inject approach.

Components Basics

Components are reusable Vue instances. In the App that I started work on in the last article, there is the main component: App.vue.

Any other components accept the same properties as the root component: data, computed, methods, watch, etc.

Three parts of a component in Vue

Single-file component vue file comprises three pieces: HTML syntax to determine the visual view for the component. JavaScript provides a list of properties for creating the component, using standard JavaScript module syntax exports in JS. Style sheets are used in defining the best user interfaces.

You have to make a new file (typically in the components folder). Let's name this file: PlayerCard.vue.

First, add a template section with HTML elements:

<template>
  <h1>This is a new component</h1>
</template>

Export Vue components

To be honest, for a long time, I thought that I needed to add another section beneath the Templates section: <script></script> and add an export object, like this:

<script>export default {}</script>

But it is not necessary. You can have components only with the template section. Anyway, typically, you have more sophisticated components in apps, so it's good to add an export default object with a name property.

<template>
    <h1>This is a new component</h1>
</template>
<script>
export default {
    name: 'PlayerdCard'
}
</script>

How to import Vue components

Since we have exported components, we can use them in another place. In this case, we are going to import the PlayerdCard Vue component into the App component. To do so, let's:

Import child components into parent components inside script tags

<script>
import PlayerCard from './components/PlayerCard.vue';

export default {
  name: 'App',
(...)

Register child component in a parent component

We need to let the App component know that it can use the PlayerdCard component. There is a components property that is responsible for registering components:

<script>
import PlayerCard from './components/PlayerCard.vue';


export default {
  name: 'App',
  components: { PlayerCard },
(...)

FINALLY. Use child component to render a child component template

To render the PlayerCard component, you must put a custom element inside the App component template. We imported the component as PlayerCard, so this is the name of the custom element:

<template>
  <PlayerCard/>
</template>

<script>
import PlayerCard from './components/PlayerCard.vue';

export default {
  name: 'App',
  components: { PlayerCard },
  // other stuff below
  data() {
    return {
      players: [
      ]
    }
  },
  computed: {
  },
  methods: {
  watch: {
  }
}
</script>
<style>
</style>

Global and local components

We registered globally our first component in App.vue, a root component. This is a typical approach, but sometimes you have specific components used in a minor part of the App.

Vue allows you to register components in other components. So you can register the component in the PlayerCard component instance, and you can use it and in any children of it then.

It means that the component is registered locally, and it will not be available in parent components - in our case, in the app component object.

Component communication

The PlayerdCard component is working, but it's not too helpful. Let's add some content to it:

<template>
  <div class="player">
    <h1>{{ player.name }}</h1>
    <img :src="player.image" :alt="player.name" />
    <p><strong>{{ player.club }}, {{ player.country }}</strong></p>
    <p>Position: {{ player.position }}</p>
    <p>
      Price: {{ player.price }}
      <strong v-if="player.playerLabel">{{ player.playerLabel }}</strong>
    </p>
    <button type="button" @click="toggleForSale()">
      <span v-if="player.forSale">Remove from transfer list</span>
      <span v-if="!player.forSale">Add to transfer list</span>
    </button>
  </div>
</template>

A player object is used in many places, but the component object does not include player data. How to pass player data to the component?

Introducing props

To pass data to the components, you can use props. Props are HTML attributes that can be, let's say, moved to the component scope.

First, we need to define that the PlayerCard component can receive a player prop:

// PlayerCard.vue
export default {
  name: "PlayerdCard",
  props: ["player"],
};

Then we can pass the player prop to the PlayerCard in App.vue

<template>
  <PlayerCard :player="players[0]" />
</template>

A player is an array defined in data of the App component:

export default {
  name: 'App',
  components: { PlayerCard },
  data() {
    return {
      players: [
        {
          id: 1,
          name: 'Mo Salah',
          club: 'Liverpool FC',
          country: 'Egypt',
          position: 'Striker',
          price: 2000,
          image: './avatar.png',
          forSale: false
        },
        {
          id: 2,
          name: 'Robert Lewandowski',
          club: 'FC Bayern',
          country: 'Poland',
          position: 'Striker',
          price: 3000,
          image: './avatar.png',
          forSale: true
        }
      ]
    }
  }
}
</script>

To make the example more accurate, let's iterate through the players' array using v for directive and display all players on the screen:

<template>
  <PlayerCard v-for="player in players" :key="player.id" :player="player" />
</template>

Supported props

Above, we passed an object as a prop, but you can also give other types. Take a look at prop types that Vue supports:

• String
• Number
• Boolean
• Array
• Object
• Date
• Function
• Symbol

Props validation

When I registered a prop in the PlayerCard component, I just pasted a name into the props array:

props: ["player"];

but there is an option to validate props. Take a look:

props: {
  player: Object;
}

Now, the component expects that player will be an object, so any other type passed to the component will throw a warning in the console.

Also, you can specify that prop is required:

props: {
    player: Object,
    required: true
}

Default value:

props: {
    player: Object,
    default: {
        name: 'Bot'
   }
}

Besides, there are more options. Please follow Vue docs to meet them all. The last thing that I want to do here is repeating Vue docs.

After this step, the App renders two players.

Custom events: child-parent communication

Our very first Vue component works, but there are some bugs. When I click on "add to transfer list," I see the error in the console:

Uncaught TypeError: _ctx.toggleForSale is not a function

That happens because, in the PlayerCard, we don't have the toggleForSale function. That function is in the scope of the App Vue component.:

methods: {
  toggleForSale() {
    this.forSale = !this.forSale;
  }
},

Anyway, that function is outdated. It worked in the case when we had one player. Now we have an array of players, so we have to update the toggleForSale function to make that possible.

methods: {
  toggleForSale(playerId) {
    const player = this.players.find(player => player.id === playerId);
    player.forSale = !player.forSale;
  }
},

Now the function receives the playerId parameter to identify which player should be modified, but still – the toggleForSale function is in the scope of the App component. Is it possible to call this method from other Vue components? Especially from child components?

There is a way to do that: custom events!

Defining custom events

To define an event, you should add it to the emits array like this:

export default {
  name: "PlayerdCard",
  props: ["player"],
  emits: ["toggle-for-sale"],
};

Technically, it's not obligatory but is a good practice to define events because then it's more clear to understand how components work.

The next step is emitting our custom event when the user clicks on the button:

<button type="button" @click="$emit('toggle-for-sale', player.id)">
  <span v-if="player.forSale">Remove from transfer list</span>
  <span v-if="!player.forSale">Add to transfer list</span>
</button>

Lastly, we have to listen to this event in the App component:

1// App.vue
<template>
  <PlayerCard
    v-for="player in players"
    :key="player.id"
    :player="player"
    @toggle-for-sale="toggleForSale"
  />
</template>

For the @toggle-for-sale custom event, I bound toggleForSale function available in App.js, and now the functionality works as expected.

Validating custom events

As props, the custom events can be validated. It's possible by defining emits not as an array but as objects. Each property of that object is a custom event name, and it's a validation function:

emits: {
    'toggle-for-sale': (playerId) => {
        if (!playerId) {
            console.warn('Player ID is missing')

            return false;
        }

        return true
    }
}

Prop drilling problem

If you came here from React, you are probably familiar with a common problem called: props drilling. If not, let me explain quickly by example.

We are going to add two components to the PlayerCard component:

• PlayerData
• PlayerAttributes

before we start implementing those components, we add some additional data to our players:

players: [
  {
    id: 1,
    name: "Mo Salah",
    club: "Liverpool FC",
    country: "Egypt",
    position: "Striker",
    price: 2000,
    image: "./avatar.png",
    forSale: false,
    birthday: "10/10/2000",
    growth: "180cm",
    betterLeg: "right",
    speed: 94,
    shooting: 90,
    passes: 89,
    dribble: 99,
    defense: 30,
    physical: 85,
  },
  {
    id: 2,
    name: "Robert Lewandowski",
    club: "FC Bayern",
    country: "Poland",
    position: "Striker",
    price: 3000,
    image: "./avatar.png",
    forSale: false,
    birthday: "20/05/2000",
    growth: "190cm",
    betterLeg: "right",
    speed: 90,
    shooting: 99,
    passes: 89,
    dribble: 85,
    defense: 78,
    physical: 89,
  },
];

The PlayerData component

// PlayerCard/PlayerData.vue

<template>
  <div class="player-data">
    <ul>
      <li>
        <strong>Birthday: </strong>
        <span>{{ player.birthday }}</span>
      </li>

      <li>
        <strong>Growth: </strong>
        <span>{{ player.growth }}</span>
      </li>

      <li>
        <strong>Better leg: </strong>
        <span>{{ player.betterLeg }}</span>
      </li>
    </ul>
  </div>
</template>
<script>
  export default {
    name: "PlayerData",
    props: ["player"],
  };
</script>

This component renders some information about a player like a birthday, growth, and better leg.

Let's import it and register in the playerCard Vue component:

<script>
import PlayerData from './PlayerCard/PlayerData.vue'

export default {
    name: 'PlayerdCard',
    props: ['player'],
    emits: ['toggle-for-sale'],
    components: {
        PlayerData
    }
}
</script>

Now we can use it in the template section:

// PlayerCard.vue

<template>
    <div class="player">
        (...)

        <div class="additional-data">
            <PlayerData :player="player"/>
        </div>
    </div>
</template>

The PlayerAttributes component

This component will be pretty the same. The difference is that it renders other data:

<template>
  <div class="player-attributes">
    <ul>
      <li>
        <strong>Speed: </strong>
        <span>{{ player.speed }}</span>
      </li>

      <li>
        <strong>Shooting: </strong>
        <span>{{ player.shooting }}</span>
      </li>

      <li>
        <strong>Passes: </strong>
        <span>{{ player.passes }}</span>
      </li>

      <li>
        <strong>Dribble: </strong>
        <span>{{ player.passes }}</span>
      </li>

      <li>
        <strong>Passes: </strong>
        <span>{{ player.dribble }}</span>
      </li>

      <li>
        <strong>Defense: </strong>
        <span>{{ player.defense }}</span>
      </li>

      <li>
        <strong>Physical: </strong>
        <span>{{ player.physical }}</span>
      </li>
    </ul>
  </div>
</template>
<script>
  export default {
    name: "PlayerData",
    props: ["player"],
  };
</script>

Note: for now, those components looks the same, but in the future, I am going to add more logic there, so don't worry, I have an idea 😆

The last thing in this step is registering, importing, and using the new component in PlayerCard.

The final code of the PlayerCard component:

<template>
  <div class="player">
    <h1>{{ player.name }}</h1>
    <img :src="player.image" :alt="player.name" />
    <p><strong>{{ player.club }}, {{ player.country }}</strong></p>
    <p>Position: {{ player.position }}</p>
    <p>
      Price: {{ player.price }}
      <strong v-if="player.playerLabel">{{ player.playerLabel }}</strong>
    </p>
    <button type="button" @click="$emit('toggle-for-sale', player.id)">
      <span v-if="player.forSale">Remove from transfer list</span>
      <span v-if="!player.forSale">Add to transfer list</span>
    </button>

    <div class="additional-data">
      <PlayerData :player="player" />
      <PlayerAttributes :player="player" />
    </div>
  </div>
</template>
<script>
  import PlayerData from "./PlayerCard/PlayerData.vue";
  import PlayerAttributes from "./PlayerCard/PlayerAttributes.vue";

  export default {
    name: "PlayerdCard",
    props: ["player"],
    emits: ["toggle-for-sale"],
    components: {
      PlayerData,
      PlayerAttributes,
    },
  };
</script>

I wanted to show you a props drilling problem if you forgot, and here you go. We have the PlayerdCard component that receives the player as a prop, and that component has children: PlayerData and PlayerAttributes components that also receive the player as a prop.

Moreover, PlayerCard's child components also can have children that need a player. A prop drilling problem is about passing props from parent to child. It can be problematic and frustrating if you have a big tree of components.

In React application, there is a way to handle that differently – by using Context. In vue, there is something familiar.

provide/inject as a solution

Instead of passing props to every child component, you can provide data in the parent component and inject this data into children. Take a look:

export default {
  name: "App",
  components: { PlayerCard },
  data() {
    return {
      players: [
        {
          id: 1,
          name: "Mo Salah",
          club: "Liverpool FC",
          country: "Egypt",
          position: "Striker",
          price: 2000,
          image: "./avatar.png",
          forSale: false,
          birthday: "10/10/2000",
          growth: "180",
          betterLeg: "right",
          speed: 94,
          shooting: 90,
          passes: 89,
          dribble: 99,
          defense: 30,
          physical: 85,
        },
        {
          id: 2,
          name: "Robert Lewandowski",
          club: "FC Bayern",
          country: "Poland",
          position: "Striker",
          price: 3000,
          image: "./avatar.png",
          forSale: false,
          birthday: "20/05/2000",
          growth: "190",
          betterLeg: "right",
          speed: 90,
          shooting: 99,
          passes: 89,
          dribble: 85,
          defense: 78,
          physical: 89,
        },
      ],
    };
  },
  provide: {
    players: this.players,
  },
};

Then in any child, you can inject players:

export default {
  name: "PlayerData",
  inject: ["player"],
};

Once I injected player into the PlayerData and PlayerAttributes component, I can remove the player prop from them in the PlayerCard component:

<div class="additional-data">
  <PlayerData />
  <PlayerAttributes />
</div>

The App still works, but data is passed differently.

Dynamic components

Last thing that I want to show you are dynamic components. Now we have two components in the PlayerCard component: PlayerData and PlayerAttributes, and they are rendered on the screen. I would like to have something like tabs and the possibility to change the active tab. Then only one component corresponding to chosen tab will be visible.

First, create a nav for tabs:

// PlayerCard.js
<nav>
  <button type="button" @click="selectTab('PlayerData')">Player Data</button>
  <button type="button" @click="selectTab('PlayerAttributes')">
    Player Attributes
  </button>
</nav>

I bound the selectTab method to click event so let's create this method:

methods: {
    selectTab(tab) {
        this.selectedTab = tab;
    }
},

Besides, add a new data property with the selectedTab field:

data() {
    return {
        selectedTab: 'PlayerData'
    }
},

Lastly, let's render our components dynamically by adding a <component> vue particular component and binding selectedTab property to is prop on that component like this:

<div class="additional-data">
  <component :is="selectedTab" />
</div>

Thanks to that, we can render dynamic components based on data property like this example. When a property is changed, Vue dynamically switch component and render them.

Complete code including dynamic components:

<template>
  <div class="player">
    <h1>{{ player.name }}</h1>
    <img :src="player.image" :alt="player.name" />
    <p><strong>{{ player.club }}, {{ player.country }}</strong></p>
    <p>Position: {{ player.position }}</p>
    <p>
      Price: {{ player.price }}
      <strong v-if="player.playerLabel">{{ player.playerLabel }}</strong>
    </p>
    <button type="button" @click="$emit('toggle-for-sale', player.id)">
      <span v-if="player.forSale">Remove from transfer list</span>
      <span v-if="!player.forSale">Add to transfer list</span>
    </button>

    <nav>
      <button type="button" @click="selectTab('PlayerData')">
        Player Data
      </button>
      <button type="button" @click="selectTab('PlayerAttributes')">
        Player Attributes
      </button>
    </nav>

    <div class="additional-data">
      <component :is="selectedTab" />
    </div>
  </div>
</template>
<script>
  import PlayerData from "./PlayerCard/PlayerData.vue";
  import PlayerAttributes from "./PlayerCard/PlayerAttributes.vue";

  export default {
    name: "PlayerdCard",
    props: ["player"],
    emits: ["toggle-for-sale"],
    provide() {
      return {
        player: this.player,
      };
    },
    components: {
      PlayerData,
      PlayerAttributes,
    },
    data() {
      return {
        selectedTab: "PlayerData",
      };
    },
    methods: {
      selectTab(tab) {
        this.selectedTab = tab;
      },
    },
  };
</script>

It isn't lovely:😎 but, don't worry – next time, I will show you how to style Vue applications.

Summary

This Vue is a Javascript framework for building web apps. As with other frameworks, it allows using reusable components. Thanks to that, frontend development and building single-page applications are easy and efficient.

Today I showed you basics about components:

• how to create and register vue component
• how components communicate with other components
• how to use props
• what is a prop drilling problem
• how to use provide/inject mechanism
• how to use dynamic components
• and so on

#WebDevelopment #FrontendDevelopment #JavaScript #VueJS #Tutorial #ConceptExplanation #DeepDive #Intermediate #ComponentArchitecture

Unknown word: Vue - this is the sentence that one of my tools that check grammar stands out to me. It's funny because, probably for most front-end developers, Vue is a known word. After all, we all love JavaScript frameworks.

I had been working with AngularJS a lot. Later I needed to learn KnockoutJS because Magento uses it. I wouldn't say I liked it(really), so I started work with React, and a few months ago, I had the opportunity to work with Vue apps, so I have begun to learn Vue.

It was not too difficult for me, and in the end, I joined the Vue Storefront team. My tiny conclusion here is frameworks are only frameworks, and when you are experienced in one of them, you can quickly learn from others.

Of course, in terms of different frameworks, API is other, the approach is different, but at the end of the day, there are if-else statements, memory leaks, and issues to solve.

The framework does not matter. It makes building user interfaces easy, but JavaScvript knowledge is a clue here, so if you are good at JavaScript, just learn the API of a framework and solve problems. In this article, I show you how to get started with Vue from the perspective of a developer who has experience in other frameworks. In this article, you won't find anything about how to print hello world in console, add 1+1, what component is, and so on. I hope you have already known the secret to how to console.log the Hello world. ;-)

Project setup using Vue CLI

In React, we have Create React App. Here you can find something similar and just as good: Vue CLI. It helps you install the Vue application. Using Vue CLI, you can manually select features you want, such as vuex, Vue router, prettier, support for TypeScript, and so on. Vue CLI will generate project files for you.

It's fair to say that setting up a Vue app using Vue CLI is an easy task. Let's try it.

First, make sure that you have Node and package manager installed. I use Node v14 and Yarn.

yarn global add @vue/cli @vue/cli-service-global
vue --version    // @vue/cli 4.5.15 for me

Navigate to the directory where you want to create a new project and use the following command:

vue create another-cool-project

I used the Default (Vue 3) ([Vue 3] babel, eslint) option, and my project was installed successfully.

🎉  Successfully created project another-cool-project.
👉  Get started with the following commands:

$ cd another-cool-project
$ yarn serve

There is a Yarn serve command that runs the development server, so let's use them, and in the meantime, I will show them the most important directories and files of the newly created project.

Vue project structure

Public directory

It contains public static files like index.html and favicon

src folder

You will spend a lot of time here because it's a place where you can find source files like components, assets, CSS files, and so on.

main.js file

Main.js is an entry point of the Vue app, and there is a JavaScript code responsible for Vue app initialization.

components directory

If you want to create a Vue component, this is the place where you will do that.

App.vue file

It's a primary component, let's say the app's root component. It's used in main.js to create a new Vue app like this:

import { createApp } from "vue";
import App from "./App.vue";

createApp(App).mount("#app");

All project files and directories should look like this in visual studio code:

Understanding Vue Files

When you see the .vue file the first time, it can be strange because there is a mix of JavaScript code, HTML, and CSS. Take a look:

<template>
  <h1>This is the title</h1>
</template>

<script>
export default {
  name: 'Title',
}
</script>

<style>
h1 {
  color: violet
}
</style>

So there are three tags: template, script, and style. The first one is the component's template, and it describes the structure of your HTML. Vue template syntax allows you to use HTML + special, let's say, directives to bind data, methods and events with HTML.

In the script tag, you define components and write JavaScript code.

The style tag is for styling. For example, you can use global styles or local (scoped), CSS, or SCSS. Details later.

Data binding

I want to create a simple app that will show cards of football players (lastly, I started to play Fifa Ultimate team, so it inspires me).

Each player has name, team, country, position, and price information. For now, we can put plain HTML to App.js:

<template>
  <div class="player">
    <h1>Robert Lewandowski</h1>
    <p><strong>FC Bayern, Poland</strong></p>
    <p>Position: Striker</p>
    <p>Price: 1000</p>
  </div>
</template>

How makes that dynamic? Each component can have a data property, a function that returns an object, and then you can use that object in templates and JavaScript code of the component.

Add data prop to the component:

export default {
  name: "App",
  data() {
    return {
      name: "Robert Lewandowski",
      club: "FC Bayern",
      country: "Poland",
      position: "Striker",
      price: 1000,
    };
  },
};

Now we can use this data in the template, and we need to bind each property to HTML. To do so we have to use {{ }} syntax for example {{ name }} will replace name with 'Robert Lewandowski' string.

Take a look:

<template>
  <div class="player">
    <h1>{{ name }}</h1>
    <p><strong>{{ club }}, {{ country }}</strong></p>
    <p>Position: { position }</p>
    <p>Price: { price }</p>
  </div>
</template>

Binding attributes or components property

Let's add a new property to the player called: image:

image: './avatar.png'

to bind this property to the src attribute of the image, you can use the v-bind directive so this code:

<img v-bind:src="image" v-bind:alt="name" />

will be rendered in the browser like this:

<img src="./avatar.png" alt="Robert Lewandowski" />

Tip: there is a shorthand for v-bind. Take a look:

<img :src="image" :alt="name" />

Conditional rendering

I have an idea to add a particular label to the player that shows if the price of a player is low or high.

For example:

• if the price is less than 5000, display 'low.'

• otherwise, display 'height.'

Vue provides vue-if and vue-else directive that allows rendering markup conditionally:

<p>
  Price: {{ price }}
  <strong v-if="price < 2000">Low</strong>
  <strong v-else>High</strong>
</p>

Remember that v-else works only when the HTML node is next to the previous, which has the v-if directive set up.

Computed properties

Let's modify the feature with labeling and add logic to our App component:

Show the label only if player is on for sale

To do so, let's add a new property to a player object called forSale:

forSale: false;

and modify v-if in the template:

<p>
  Price: {{ price }}
  <strong v-if="price < 2000 && forSale">Low</strong>
  <strong v-if="price <= 2000 && forSale">High</strong>
</p>

It works but is a little bit freaky. Putting logic to the temple is not a good idea, even in such a simple example. Don't worry. Vue has a lovely mechanism for handling situations like that: computed properties responsible for managing complex logic.

Take a look at how to define computed property:

export default {
  name: 'App',
  data() {
   // data here
  },
  computed: {
    playerLabel: function () {
      if (!this.forSale) {
          return null;
        }

        return (this.price < 2000) ? 'Low' : 'High'
    }
  }
}
</script>

Note: The 'this' keyword in the code refers to the Vue instance.

Now you can use it in the template like this:

<strong v-if="playerLabel">{{ playerLabel }}</strong>

Important note: computed properties are cached based on their reactive dependencies. In our case, that means that the template will re-render computed property only if the forSale flag or price is changed.

If you come from React, you can compare computed properties to the useMemo hook.

Methods

When you create a web app, the common thing is to bind events to a javascript code or, let say, methods.

A methods option allows you to add methods to the Vue components. Let's create a method that toggles the forSale flag.

export default {
  name: 'App',
  data() {
    // data here
  },
  computed: {
    // computed properties
  },
  methods: {
    toggleForSale() {
      this.forSale = !this.forSale;
    }
  }
}
</script>

So we have the method declared and bind it to the DOM element? First, let's create a button:

<button type="button">
  <span v-if="forSale">Remove from transfer list</span>
  <span v-if="!forSale">Add to transfer list</span>
</button>

To attach an event to the method, we need to use the v-on directive. In our case, we want to connect the method to the click event:

<button type="button" v-on:click="toggleForSale"></button>

You can also use something like this:

<button type="button" @click="toggleForSale"></button>

Note: I will show you more about events later.

Watchers

Sometimes you need to watch when the specific property is changed and run some code. Vue provided a watch option. Take a look:

export default {
  name: "App",
  data() {},
  computed: {},
  methods: {},
  watch: {
    forSale(oldValue, newValue) {
      console.log(oldValue, newValue);
      // here you can a logic fired when forSale property is changed
      // for example an http request to external API can be fired here
      // axios.post(...)
    },
  },
};

Iterating through data

Let's imagine that we have more than one player, and we want to display all of them. First, of course, we need to modify our data object:

data() {
  return {
    players: [
      {
        id: 1,
        name: 'Mo Salah',
        club: 'Liverpool FC',
        country: 'Egypt',
        position: 'Striker',
        price: 2000,
        image: './avatar.png',
        forSale: false
      },
      {
        id: 2
        name: 'Robert Lewandowski',
        club: 'FC Bayern',
        country: 'Poland',
        position: 'Striker',
        price: 3000,
        image: './avatar.png',
        forSale: true
      }
    ]
  }
},

Please notice that I added the id property to each player object. We will use it later.

To iterate through the array we need to use the v-for directive:

<template>
  <div class="player" v-for="player in players" :key="player.id">
    <h1>{{ player.name }}</h1>
    <img :src="player.image" :alt="player.name" />
    <p><strong>{{ player.club }}, {{ player.country }}</strong></p>
    <p>Position: {{ player.position }}</p>
    <p>
      Price: {{ player.price }}
      <strong v-if="player.playerLabel">{{ player.playerLabel }}</strong>
    </p>
    <button type="button" @click="toggleForSale()">
      <span v-if="player.forSale">Remove from transfer list</span>
      <span v-if="!player.forSale">Add to transfer list</span>
    </button>
  </div>
</template>

So using v-for, we repeat in the players' array, and we get a player. Then we can access a player's object properties using a player reference like a player.name, player. image etc.

Note: after this change, our price label and event listeners stopped working, and this is great because we have another problem to solve!

We will solve that by creating a player component, but... in the following article.

Summary

Vue is a great, progressive framework that can be a good choice even for a large application when you think about a view layer.

Today, I showed you some basics about creating web apps using Vue, but only a minor part. In the following articles, I would like to show you some more advanced features like:

• Vue components
• styling
• events
• state management
• forms
• communication with APIs
• testing
• and so on

#WebDevelopment #FrontendDevelopment #JavaScript #VueJS #Angular #React #VueCLI #Tutorial #ConceptExplanation #QuickTip #Beginner

In one of my previous articles, I described GraphQL queries. Today I would like to show you how to work with GraphQL mutations.

What is a mutation in GraphQL?

A mutation is a function that allows you to modify data. In REST APIs, data is typically fetched by the GET method and added or modified by the POST or PUT method.

In GraphQL, there are two types of operations:

1. Query: fetching data

2. Mutation: modifying/adding data

Mutation example

Take a look at the simple mutation from the Magento eCommerce platform's GraphQL API that creates an empty cart:

mutation {
  createEmptyCart(input: {})
}

Mutation receives an empty input object and returns a token of the newly created cart.

Let's try something more complicated - a mutation that takes some input via variables:

mutation {
  addSimpleProductsToCart(input: { cart_id: "B06YCRcXAaOHGTtZ2Iij8SDHAq0AR49F", cart_items: [{ data:{sku: "24-MB01", quantity: 1} }] }) {
    cart {
      total_quantity
      items {
        product {
          name
        }
      }
    }
  }
}

In this example, you can see the addSimpleProductsToCart mutation that takes an input object with the following variables:

• cart_id: Cart ID to which the product will be added

• cart_items: array of objects that contains the SKU of the product and its quantity. The example above adds one product of SKU 24-MB0_1 to the cart with ID _B06YCRcXAaOHGTtZ2Iij8SDHAq0AR49F

Mutation returns the cart object, and in this example, I requested total_quantity of the cart and information about the cart items' names.

The response to that GraphQL mutation looks like this:

{
  "data": {
    "addSimpleProductsToCart": {
      "cart": {
        "total_quantity": 1,
        "items": [
          {
            "product": {
              "name": "Joust Duffle Bag"
            }
          }
        ]
      }
    }
  }
}

Hard-coding variables is not a good idea in real projects, so take a look at an example where I pass variables by arguments:

mutation addSimpleProductsToCart($input: AddSimpleProductsToCartInput ) {
  addSimpleProductsToCart(input: $input) {
    cart {
      total_quantity
      items {
        product {
          name
        }
      }
    }
  }
}

In this case, you can pass variables as an object:

{
  "input": {
    "cart_id": "B06YCRcXAaOHGTtZ2Iij8SDHAq0AR49F",
    "cart_items": [
      {
        "data": {
          "sku": "24-MB01",
          "quantity": 1
        }
      }
    ]
  }
}

Apollo Client

Apollo Client is one of the most popular GraphQL clients for React, and in this article, I want to show you how to work with mutations using Apollo Client and React.

Prerequisites

If you want to run the examples below on your computer, you should:

1. Set app a new React App using https://create-react-app.dev/docs/getting-started

2. https://www.apollographql.com/docs/react/get-started/ (note: I used Magento GraphQL API in examples, but it is up to you which API you would like to use)

Execute mutation in Apollo client

Apollo Client offers predefined hooks to execute GraphQL queries and mutations. These hooks offer much more than only sending requests and receiving responses. Let's go dive to see what the useMutation hook provides.

The useMutation hook

Let's see how the useMutation hook works with a real example*.* To do so, I use the createEmptyCart mutation. First, I need to define that mutation in the code:

import { gql, useMutation } from "@apollo/client";

const CREATE_EMPTY_CART = gql`
  mutation {
    createEmptyCart(input: {})
  }
`;

That GraphQL operation takes no arguments so executing is very simple and looks like this:

useMutation(CREATE_EMPTY_CART);

Full example:

import { gql, useMutation } from "@apollo/client";

const CREATE_EMPTY_CART = gql`
  mutation {
    createEmptyCart(input: {})
  }
`;

function App() {
  const [mutateFunction, { data, loading, error, called, reset }] =
    useMutation(CREATE_EMPTY_CART);

  if (loading) {
    return <>Loading...</>;
  }

  return (
    <main style={{ padding: "10px" }}>
      <h1>GraphQL mutations tutorial</h1>
      <button type="button" onClick={() => mutateFunction()}>
        Create cart
      </button>

      <div>
        <h2>Data: </h2>
        {data && data.createEmptyCart}
      </div>
      {error && (
        <div>
          <h2>Error:</h2>
          {error.toString()}
        </div>
      )}
      <div>
        <h2>Called: {called.toString()}</h2>
        <button type="button" onClick={() => reset()}>
          Reset
        </button>
      </div>
    </main>
  );
}

export default App;

This part of the code:

const [mutateFunction, { data, loading, error }] = useMutation(CREATE_EMPTY_CART);

Is responsible for initializing the useMutation hook in the component

Mutation response

The useMutation hook returns an array that contains mutate function and an object with some properties.

mutate Function

A function that must be called to execute mutation. This example is named as mutateFunction, but you can name it what you want for example, you can use the operation name: createEmptyCart, or whatever you want.

The code below is responsible for executing mutation:

<button type="button" onClick={() => mutateFunction()}>Create cart</button>

Basically, there is a button that has bounded the mutate function on the click event. So when the user clicks that button, the mutation will be executed.

data

The data fields contain the mutation response. Then you can use this data in the component. In this example, I display the mutation response on the screen:

<div>
  <h2>Data:</h2>
  {data && data.createEmptyCart}
</div>

LOADING

The loading fields show the state of the mutation. If it's true, that means that mutation is in progress and fetches data at the moment. When mutation returns value and execution is finished, the loading field equals false.

In this example, I use the loading field only to display the loading information on the screen:

if (loading) {
  return <>Loading...</>;
}

error

When mutation meets some errors on the backend side, they will be returned here. The error object can contain either an array of graphQLErrors objects or one single networkError object. If GraphQL server doesn't produce any error, the error object is undefined.

In my example, I display potential errors on the screen:

{
  error && (
    <div>
      <h2>Error:</h2>
      {error.toString()}
    </div>
  );
}

called

The called is a flag that describes if mutate function is called or not.

Reset

When you want to rest the mutation state to initial, you call the reset() function. That means Apolo will restore all fields returned by the useMutation hook. to default values.

Mutation options

The previous example was straightforward. I didn't even pass any variables there. Let's see something more sophisticated. To pass additional parameters to the useMutation hook, you must pass an object as a second argument to the operation.

const [mutateFunction, { data, loading, error, called, reset }] = useMutation(
  MUTATION_STRING,
  {
    // additional options here
  },
);

Note: MUTATION_STRING is a GraphQL query string parsed with the gql template literal.

Variables

The variables object allows passing GraphQL variables to the mutation. Each key in this object represents one variable.

const CREATE_EMPTY_CART = gql`
   mutation createCart($input: createEmptyCartInput) {
    createEmptyCart(input: $input)
  }
`;

function App() {
  const [mutateFunction, { data, loading, error, called, reset }] = useMutation(CREATE_EMPTY_CART, {
    variables: {
      input: {
        cart_id: 'lTO8UjTglq5djnpIOseLN7RWvpvwSRba'
      }
    }
  });

 (...) // rest of the code

I updated the mutation string, and from now it accepts one argument: $input object:

mutation createCart($input: createEmptyCartInput) {
    createEmptyCart(input: $input)
}

Then I passed the variables object to the useMutation hook:

const [mutateFunction, { data, loading, error, called, reset }] = useMutation(
  CREATE_EMPTY_CART,
  {
    variables: {
      input: {
        cart_id: "lTO8UjTglq5djnpIOseLN7RWvpvwSRba",
      },
    },
  },
);

errorPolicy

The errorPolicy field allows specifying how the hook handles errors.

Possible values:

• None (default value) - if the response contains errors, they are returned on the error object, and data is undefined.

• Ignore - errors are skipped, so the error object is not populated even if something goes wrong.

• All - two objects: data and error, are populated. This is useful if you want to settle partial data even if something went wrong during the mutation execution.

onCompleted

The onCompleted is a callback function called when the mutation was executed without errors. In this function, you can access mutation results and options passed to the mutation. Take a look at the example:

import { gql, useMutation } from "@apollo/client";

const ADD_PRODUCT_TO_CART = gql`
  mutation AddProductsToCart($cartId: String!, $cartItems: [CartItemInput!]!) {
    addProductsToCart(cartId: $cartId, cartItems: $cartItems) {
      cart {
        id
        items {
          quantity
          prices {
            row_total {
              currency
              value
            }
          }
        }
        prices {
          grand_total {
            currency
            value
          }
        }
        total_quantity
      }
    }
  }
`;

const [addProductToCart] = useMutation(ADD_PRODUCT_TO_CART, {
  variables: {
    cartId: "koESgYi6WU5BiCJDRkgfilDB4z1IsfHV",
    cartItems: [
      {
        selected_options: ["Y29uZmlndXJhYmxlLzE0NC8yMTU"],
        quantity: 1,
        sku: "GC-747-SOCK",
      },
    ],
  },
  onCompleted: (data, options) => {
    console.log(data, options);
  },
});

// (...)
<button type="button" onClick={() => addProductToCart()}>
  Add product to cart
</button>;

onError

The onError is a callback function called when a mutation returns some error. In this function, you can access the error object and options passed to the mutation.

Updating the cache

Apollo client has its own caching system and, by default, writes data to the cache. The cache impacts the speed of operation, because some operations can retrieve data only from the cache or first from the cache and then from the server.

In addition, a technique called optimistic responses can be used in working with mutations. Let me explain this to you with an example:

1. The user enters the website

2. Apollo downloads a list of products and displays them on the screen

3. The user adds a product to the basket

4. Storefront needs to update the shopping cart details.

After executing the mutation, we have two to accomplish this:

1. Update the cart data in the cache

2. Perform the shopping cart inquiry again

Let's see how to implement this in Apollo.

How Apollo Updates the cache

First, let's create a new query that fetches the cart:

const GET_CART = gql`
  query getCart {
    cart(cart_id: "koESgYi6WU5BiCJDRkgfilDB4z1IsfHV") {
      id
      items {
        quantity
        prices {
          row_total {
            currency
            value
          }
        }
      }
      prices {
        grand_total {
          currency
          value
        }
      }
      total_quantity
    }
  }
`;

Second, use the useLazyQuery hook to execute the query:

const [getCart] = useLazyQuery(GET_CART, {
  onCompleted: (data) => {
    console.log("cart data: ", data);
  },
});

Third, add a button and bind the getCart function to the onClick event of that button:

<button type="button" onClick={() => getCart()}>
  Get cart
</button>

When the user clicks that button, the query is executed and the onCompleted callback prints cart data to the console.

At the same time, Apollo writes data of that cart to the cache.

Now, when the user clicks Add Product to cart button, Apollo runs the addProductToCart mutation, and the product will be added to the cart on the server side. Under the hood, Apollo updates the cart data in the cache.

Updating cache manually

In some cases, Apollo is not able to update the cache automatically. Then you can define your own update function and write to the cache manually. You can pass an update function as a field of the settings object that useMutation hook receives:

import { gql, useMutation } from "@apollo/client";

const [addProductToCart] = useMutation(ADD_PRODUCT_TO_CART, {
  // (...)
  update(cache, { data: { addProductsToCart } }) {
    cache.modify({
      fields: {
        cart(existingCartRef = {}) {
          const newCartRef = cache.writeFragment({
            data: addProductsToCart.cart,
            fragment: gql`
              fragment NewCart on Cart {
                id
                items {
                  quantity
                  prices {
                    row_total {
                      currency
                      value
                    }
                  }
                }
                prices {
                  grand_total {
                    currency
                    value
                  }
                }
                total_quantity
              }
            `,
          });
          return { ...existingCartRef, newCartRef };
        },
      },
    });
  },
});

The update function receives the cache object and data returned by the mutation.

On the cache object, there is the modify function that allows updating the cache. In that function, I create a new cart fragment that contains data returned from mutation, and at the end, I return the merged cache cart with a new cart. Then Apollo updates the cache.

refetchQueries

Another mechanism to update the state after mutation execution is refetching queries. You can specify which queries should be executed by passing them to the refetchQueries array.

const [addProductToCart] = useMutation(ADD_PRODUCT_TO_CART, {
  // (...)
  refetchQueries: ["getCart"],
});

the "getCart" is the query defined earlier:

const GET_CART = gql`
  query getCart {
     // (...)
  }
`;

Alternatively, you can pass the query as an object like this:

const GET_CART = gql`
  query getCart {
     // (...)
  }
`;

// (...)

const [addProductToCart] = useMutation(ADD_PRODUCT_TO_CART, {
  // (...)
  refetchQueries: [{ query: GET_CART }],
});

Optimistic responses

When you perform graphql mutations, they modify server-side data, which can take some time. You would have new data as fast as possible and display it to the user. Apollo provides an interesting mechanism: Optimistic mutation results, and thanks to this feature, you can update your UI before your server responds. Take a look at how it works:

const [addProductToCart] = useMutation(ADD_PRODUCT_TO_CART, {
  // (...)
  optimisticResponse: {
    addProductsToCart: {
      cart: {
        id: "koESgYi6WU5BiCJDRkgfilDB4z1IsfHV",
        __typename: "Cart",
        total_quantity: 40,
        // other cart fields
      },
    },
  },
});

The optimisticResponse object takes an object with the same structure as the expected mutation response. When the mutate function is called, UI will be updated. Finally, when a request is done, Apollo replaces the fake data you specified with real server side data.

Conclusion

Mutations next to queries are the core of Apollo Client's API. Sending a request and receiving a response is not all that Apollo Client offers. Thanks to the fact that Apollo has its state, developers can reliably program communication with the API and provide users with a very good UX. One of the most interesting features is optimistic responses, thanks to which the UI will seem fast even when the server is slow.

#WebDevelopment #FrontendDevelopment #BackendDevelopment #JavaScript #React #GraphQL #ApolloClient #REST #ConceptExplanation #Tutorial #DeepDive #Intermediate #DataPipeline #PerformanceOptimization

In one of my previous articles, I described the useReducer hook as an excellent way to manage the state of React apps, including apps connected with GraphQL APIs using the apollo client.

Typically in an app, you have a remote state (from sever, for API, here I mean from GraphQL API), but also you can have a local state that does not exist on the server side.

I said that useReducer is suitable for managing situations like that – moreover – using Apollo Client, there is another way to manage the local state.

Apollo Client for State Management

Apollo client 3 enables the management of a local state by incorporating field policies and reactive variables. Field Policy lets you specify what happens if you query specific fields, including those not specified for your GraphQL servers. Field policies define local fields so the field is populated with information stored anywhere, like local storage and reactive variables.

So Apollo Client (version >=3) provides two mechanisms to handle the local state:

• Local-only fields and field policies

• Reactive variables

What is the Apollo client?

The Apollo client connects React App and GraphQL API. Moreover, it is a state management library.

It helps you to connect your React App with GraphQL API. It provides methods to communicate with API, cache mechanisms, helpers, etc.

Besides, Apollo client provides an integrated state management system that allows you to manage the state of your whole application.

What is Apollo State?

Apollo Client has its state management system using GraphQL to communicate directly with external servers and provide scalability.

Apollo Client supports managing the local and remote state of applications, and you will be able to interact with any state on any device with the same API.

Local-only fields and field policies

This mechanism allows you to create your client schema. You can extend a server schema or add new fields.

Then, you can define field policies that describe wherefrom data came from. You can use Apollo cache or local storage.

The crucial advantage of this mechanism is using the same API as when you work with server schema.

Local state example

If you want to handle local data inside a standard GraphQL query, you have to use a @client directive for local fields:

query getMissions ($limit: Int!){
    missions(limit: $limit) {
        id
        name
        twitter
        website
        wikipedia
        links @client // this field is local
    }
}

Define local state using local-only fields

InMemory cache from Apollo

Apollo client provides a caching system for local data. Normalized data is saved in memory, and thanks to that, already cached data can get fast.

Field type policies

You can read and write to the Apollo client cache. Moreover, you can customize how a specific field in your cache is handled. You can specify read, write, and merge functions and add custom logic.

To define a local state, you need to:

1. Define field policy and pass it to the InMemoryCache

2. Add field to the query with @client directive

Local-only fields tutorial

Let's go deeper with the local-only field and check how they work in action.

Initialize the project using Create React App

npx create-react-app local-only-fields

Install apollo client

npm install @apollo/client graphql   

Initialize Apollo client

Import apollo client stuff in index.js:

import { ApolloClient, InMemoryCache, ApolloProvider } from "@apollo/client";

Create client instance

const client = new ApolloClient({
  uri: "https://api.spacex.land/graphql/",
  cache: new InMemoryCache(),
});

API.spacex.land/graphql is a fantastic free public demo of GraphQL API, so I use it here. If you want to explore that API, copy the URL to the browser: https://api.spacex.land/graphql/

Connect Apollo with React by wrapping the App component with ApolloProvider:

<ApolloProvider client={client}>
       
  <App />
</ApolloProvider>

ApolloProvider takes the client argument, which is our already declared Apollo Client. We can use Apollo Client features in the App component and every child component, thanks to that.

The query for missions data

Let's get some data from the API. I want to get missions:

query getMissions ($limit: Int!){
  missions(limit: $limit) {
    id
    name
    twitter
    website
    wikipedia
  }
}

Results for this query when I passed 3 as a limit variable:

{
  "data": {
    "missions": [
      {
        "id": "9D1B7E0",
        "name": "Thaicom",
        "twitter": "https://twitter.com/thaicomplc",
        "website": "http://www.thaicom.net/en/satellites/overview",
        "wikipedia": "https://en.wikipedia.org/wiki/Thaicom"
      },
      {
        "id": "F4F83DE",
        "name": "Telstar",
        "twitter": null,
        "website": "https://www.telesat.com/",
        "wikipedia": "https://en.wikipedia.org/wiki/Telesat"
      },
      {
        "id": "F3364BF",
        "name": "Iridium NEXT",
        "twitter": "https://twitter.com/IridiumBoss?lang=en",
        "website": "https://www.iridiumnext.com/",
        "wikipedia": "https://en.wikipedia.org/wiki/Iridium_satellite_constellation"
      }
    ]
  }
}

Let's create a React component that receives that data and, for now, displays the name of the Mission on the screen.

First, create a unit test: src/components/Missions/__tests__/Missions.spec.js

import { render } from "@testing-library/react";
import Missions from "../Missions";
describe("Missions component", () => {
  it("Should display name of each mission", () => {
    const { getByText } = render(<Missions />);
    getByText("Missions component should be here.");
  });
});

Of course, the test fails because we event doesn't have a component created yet.

Add Component: src/components/Missions/Missions.js

import React from "react";
export const Missions = () => {
  return <div>       Missions component should be here.    </div>;
};
export default Missions;

Now the test is passing

Let's re-export component in src/components/Missions/index.js

export { default } from "./Missions";

We need to query for data using the useQuery hook provided by the Apollo client.

In unit tests, you need to have a component wrapped by ApolloProvider. For testing purposes, Apollo provides a unique Provider: MockedProvider, and it allows you to add some mock data. Let's use it.

// src/components/Missions/__tests__/Missions.spec.js

import MockedProvider:
 
import { MockedProvider } from '@apollo/client/testing';

Define mocks:

const mocks = [
   {
       request: {
           query: GET_MISSIONS,
           variables: {
               limit: 3,
           },
       },
       result: {
           "data": {
               "missions": [
               {
                   "id": "9D1B7E0",
                   "name": "Thaicom",
                   "twitter": "https://twitter.com/thaicomplc",
                   "website": "http://www.thaicom.net/en/satellites/overview",
                   "wikipedia": "https://en.wikipedia.org/wiki/Thaicom"
               },
               {
                   "id": "F4F83DE",
                   "name": "Telstar",
                   "twitter": null,
                   "website": "https://www.telesat.com/",
                   "wikipedia": "https://en.wikipedia.org/wiki/Telesat"
               },
               {
                   "id": "F3364BF",
                   "name": "Iridium NEXT",
                   "twitter": "https://twitter.com/IridiumBoss?lang=en",
                   "website": "https://www.iridiumnext.com/",
                   "wikipedia": "https://en.wikipedia.org/wiki/Iridium_satellite_constellation"
               }
               ]
           }
       }
   },
];

The test fails because we don't have the GET_MISSIONS query defined yet.

Create the file queries/missions.gql.js with the following content:

import { gql } from "@apollo/client";
export const GET_MISSIONS = gql`
   query getMissions ($limit: Int!){
       missions(limit: $limit) {
           id
           name
           twitter
           website
           wikipedia
       }
   } 
`;

Import query in the src/components/Missions/__tests__/Missions.spec.js

import { GET_MISSIONS } from "../../../queries/missions.gql";

Now let's wrap the Missions component by the Mocked provider.

const { getByText } = render(
  <MockedProvider mocks={mocks}>
          
    <Missions />
       
  </MockedProvider>,
);

Now, we can expect that three product missions are visible on the screen because, in our mock response, we have an array with three missions with corresponding names: 'Thaicom,' 'Telstar,' and 'Iridium NEXT.'

To do so, update the test case.

First, make the test case asynchronous by adding the async keyword before the it callback function.

Second, replace the getByText query with the findByText, which works asynchronously.

it("Should display name of each mission", async () => {
  const { findByText } = render(
    <MockedProvider mocks={mocks}>
                     
      <Missions />
                 
    </MockedProvider>,
  );
  await findByText("Thaicom");
  await findByText("Telstar");
  await findByText("Iridium NEXT");
});

The test fails because we don't query for the data in React component.

By the way, maybe, you think I don't wrap findBytext by the expect…toBe. I do not do that because the findByText query throws an error when it cannot find provided text as an argument, so I don't have to create an assertion because the test will fail if the text is not found.

Let's update the React component.

First import useQuery hook, and GET_MISSIONS query in src/components/Missions/Missions.js

import { useQuery } from "@apollo/client";
import { GET_MISSIONS } from "../../queries/missions.gql";

Let's query for the data in the component body:

const { data } = useQuery(GET_MISSIONS, {
  variables: {
    limit: 3,
  },
});

Now, let's prepare content that Component will render for us. If missions exist, allow's display the name of each Mission. Otherwise, let's show the 'There is no missions' paragraph.

const shouldDisplayMissions = useMemo(() => {
  if (data?.missions?.length) {
    return data.missions.map((mission) => {
      return (
        <div key={mission.id}>
          <h2>{mission.name}</h2>
        </div>
      );
    });
  }

  return <h2>There are no missions</h2>;
}, [data]);

In the end, the Component needs to return shouldDisplayMissions:

import React, { useMemo } from "react";
import { useQuery } from "@apollo/client";
import { GET_MISSIONS } from "../../queries/missions.gql";
export const Missions = () => {
  const { data } = useQuery(GET_MISSIONS, {
    variables: {
      limit: 3,
    },
  });
  const shouldDisplayMissions = useMemo(() => {
    if (data?.missions?.length) {
      return data.missions.map((mission) => {
        return (
          <div key={mission.id}>
                               <h2>{mission.name}</h2>
                           
          </div>
        );
      });
    }
    return <h2>There are no missions</h2>;
  }, [data]);
  return shouldDisplayMissions;
};
export default Missions;

Now, the test pass!

The last thing for this step is to inject components into the app and see missions in the browser.

// App.js

import Missions from "./components/Missions";
function App() {
  return <Missions />;
}
export default App;

It works but, initially, it shows, "There are no missions." Let fix it by adding a loading indicator in Missions.js.

First, grab the loading flag from the useQuery hook results:

const { data, loading } = useQuery(GET_MISSIONS, {
  variables: {
    limit: 3,
  },
});

Add loading indicator:

if (loading) {
    return <p>Loading...</p>
}

return shouldDisplayMissions;

Besides, add a little bit of styling.

//src/components/Missions/Missions.module.css
.mission {
   border-bottom: 1px solid black;
   padding: 15px;
}

Now, import CSS module in Missions.js file:

import classes from './Missions.module.css'

and add mission class to the mission div:

return (
  <div key={mission.id} className={classes.mission}>
    <h2>{mission.name}</h2>
  </div>
);

Add local-only field

OK, so we have data from API. The next task is to display links for the Mission. API returns three fields:

• twitter

• website

• Wikipedia

We can create our local field called: links. It will be an array with links, so we can loop through that array and just display links.

First, let's add a new test case:

it("Should display links for the mission", async () => {
  const localMocks = [
    {
      ...mocks[0],
      result: {
        data: {
          missions: [
            {
              id: "F4F83DE",
              name: "Telstar",
              links: ["https://www.telesat.com/"],
            },
          ],
        },
      },
    },
  ];
  const { findByText } = render(
    <MockedProvider mocks={localMocks}>
      <Missions />
    </MockedProvider>,
  );

  await findByText('https://www.telesat.com/"');
});

So, we expect that there will be rendered one link: "https://www.telesat.com/"

Define field policy

First, we must define the field policy for our local links field.

When you inspect docs for missions query in GraphQL API, you can see that it returns a Mission type.

So we need to add a links client field to the Mission type.

To do so, we need to add a configuration to InMeMoryCache in the src/index.js file like this:

const client = new ApolloClient({
 uri: 'https://api.spacex.land/graphql/',
 cache: new InMemoryCache({
   typePolicies: {
     Mission: {
       fields: {
         links: {
           read(_, { readField }) {
             // logic will be added here in the next step
           }
         }
       }
     }
   }
 })

Now let's return an array with links collected from the Mission. The read function has two arguments. The first one is the field's currently cached value if one exists. The second one is an object that provides several properties and helper functions. We will use the readField function to read other field data.

Our logic for the links local field:

read(_, { readField }) {
    const twitter = readField('twiiter');
    const wikipedia = readField('wikipedia');
    const website = readField('website');
    const links = [];


    if (twitter) {
      links.push(twitter);
    }


    if (wikipedia) {
      links.push(wikipedia);
    }


    if (website) {
      links.push(website);
    }


    return links;
  }

The query for local-only field

The next step is to include the links field in the query. Let's modify the GET_MISSIONS query:

query getMissions ($limit: Int!){
    missions(limit: $limit) {
        id
        name
        twitter
        website
        wikipedia
        links @client
    }
}

You can define the local-only field by adding the @client directive after the field name.

Display local-only field on the screen

We have made good progress, but the test still fails because the Component does not render any links yet.

Please update the Missions component by modifying the shouldDisplayMissions Memo function.

const shouldDisplayMissions = useMemo(() => {
  if (data?.missions?.length) {
    return data.missions.map((mission) => {
      const shouldDisplayLinks = mission.links?.length
        ? mission.links.map((link) => {
            return (
              <li key={`${mission.id}-${link}`}>
                <a href={link}>{link}</a>
              </li>
            );
          })
        : null;

      return (
        <div key={mission.id} className={classes.mission}>
          <h2>{mission.name}</h2>
          {shouldDisplayLinks}
        </div>
      );
    });
  }

  return <h2>There are no missions</h2>;
}, [data]);

We are good now. Everything work as well in the browser:

Working Demo

Here you can see the demo of the app:

https://apollo-client-local-only-fields-tutorial.vercel.app/

Source code

Here you can find the source code for this tutorial: https://github.com/Frodigo/apollo-client-local-only-fields-tutorial

Here are the commits for each step:

1. https://github.com/Frodigo/apollo-client-local-only-fields-tutorial/commit/57cef8a41077571f8a60675ec81882d8b71a6b89

2. https://github.com/Frodigo/apollo-client-local-only-fields-tutorial/commit/595bf812f93c9a104d1f6983c6d046d432104bbe

3. https://github.com/Frodigo/apollo-client-local-only-fields-tutorial/commit/e32ab19d6a54b70bb44d92a2754a9538c73ad667

4. https://github.com/Frodigo/apollo-client-local-only-fields-tutorial/commit/0212eeca03b4768c1b163da355083e984e276668

5. https://github.com/Frodigo/apollo-client-local-only-fields-tutorial/commit/71b004f013826c4eb58da045230d36334716acde

Reactive variables

OK, you met local-only fields, and now let's look at another mechanism called: Reactive variables.

You can write and read data anywhere in your app using reactive variables.

Apollo client doesn't store reactive variables in its cache, so you don't have to keep the strict cached data structure.

Apollo client detects changes in reactive variables, and when the value changes, a variable is automatically updated in all places.

Reactive variables in action

This time I would like to show you the case using reactive variables. I don't want to repeat Apollo docs, so you can see the basics of reading and modifying reactive variables https://www.apollographql.com/docs/react/local-state/reactive-variables/.

The case

I've started work on the cart and mini-cart in my react-apollo-storefront app. The first thing that I needed to do was create an empty cart.

In Magento GraphQL API, there is the mutation createEmptyCart. That mutation returns the cart ID.

I wanted to get a cart ID, store it in my app, and after the page refresh, check if a value exists in the local state and, if yes, get it from it without running mutation.

Implementation

First, let's define the reactive variable:

import { makeVar } from "@apollo/client";

export const CART_ID_IDENTIFER = "currentCardId";
export const cartId = makeVar(localStorage.getItem(CART_ID_IDENTIFER));

Second, use that variable in a component, context, or hook and make it reactive:

import { useReactiveVar } from '@apollo/client';

export const CartProvider = ({ children }) => {
    const currentCartId = useReactiveVar(cartId);
};

Third, define the mutation to collect a cart Id from the server:

// mutation:
import { gql } from "@apollo/client";

export const CREATE_EMPTY_CART = gql`
    mutation createEmptyCart {
        createEmptyCart
    }
`;

// component
// imports
import { useMutation } from "@apollo/client";
import { CREATE_EMPTY_CART } from "../../mutations/cart.gql";

// ... in component body
const [createEmptyCart] = useMutation(CREATE_EMPTY_CART, {
  update(_, { data: { createEmptyCart } }) {
    cartId(createEmptyCart);
    localStorage.setItem(CART_ID_IDENTIFER, createEmptyCart);
  },
});

I used the update callback there, and I updated the reactive variable:

cartId(createEmptyCart)

Then I also updated a value in the local storage.

Last, check if the cart ID exists in the local state and if not, send the mutation to a sever.

const currentCartId = useReactiveVar(cartId);

useEffect(() => {
  if (!currentCartId) {
    createEmptyCart();
  }
}, [createEmptyCart, currentCartId]);

Summary

Today I showed you two techniques for managing local data in Apollo. Local-only fields and reactive variables. Those mechanisms provide a lot of flexibility, and they should be considered when architecting state management in your React application.

#WebDevelopment #FrontendDevelopment #ProgrammingFundamentals #JavaScript #React #Apollo #GraphQL #REST #Tutorial #DeepDive #ConceptExplanation #Intermediate #StateManagement #DataPipeline #APIIntegration

When React renders a component that calls the useQuery hook, the Apollo Client runs the query automatically, but sometimes you need to query for data on some event. A great case is a quick search component that allows users to search for products in an eCommerce store.

There is a useLazyQuery hook that returns a query function. You can use this function wherever you want, and when you fire it, Apollo will execute a query for you.

When would you use lazy queries?

Typically custom Apollo's hook useQuery is used when you want to query data. That kook is called when React mounts and renders the component, and Apollo Client automatically executes a query then.

What to do when you want to call a query manually thought? For instance, when a user clicks on a specific button, or if you're running a query in a useEffect function?

Lazy queries for the rescue

In that case, you can use the useLazyQuery hook. As I mentioned earlier, It's pretty much the same as useQuery with one exception. When useLazyQuery is called, it does not immediately execute its associated query.

Instead, it returns a function in its result tuple that you can call whenever you're ready to execute the query.

On the other hand, the useLazyQuery hook is ideal for executing queries in response to different events, such as user actions. Whenever the useLazyQuery command occurs, the application will not immediately run any queries. You need to trigger a query manually.

Take a look at the example

import React from "react";
import { useLazyQuery } from "@apollo/client";
import { GET_SWEETIES } from "./somewhere";

const MySweeties = () => {
  const [getSweeties, { loading, data }] = useLazyQuery(GET_SWEETIES);

  if (loading) return <p>Loading ...</p>;

  const shouldDisplaySweeties =
    data && data.sweeties ? (
      <img src={data.sweeties.image} alt="sweeties" />
    ) : (
      <button onClick={() => getSweeties({ variables: { type: "chocolate" } })}>
            Get sweeties!   
      </button>
    );

  return shouldDisplaySweeties;
};

How useful is that?

Refetch function

The useQuery returns data, and the useLazyQuery returns data as well. Those hooks return cached data or server data. It doesn't matter, they return the requested data and the component renders that data. The default behavior of the useQuery hook is to perform a query when the component re renders. Lazy query allows performing a query on demand.

Moreover, an additional mechanism allows to refetch queries on demand to particular user action. Take a look at the example:

const { loading, error, data, refetch } = useQuery(YOUR_QERY, {
  variables: { sampleVar: "abc" },
});

You can bind refetch function in the JSX code like this:

<button onClick={() => refetch({ sampleVar: "xyz" })}>Refetch</button>

As you can see, you can pass new variables to the function.

Practical usage

Let's use that knowledge about lazy queries and implement a QuickSearch component in the React app.

QuickSearch component

Create a quick search component with the following content:

import React, { useState } from "react";
import { Form, FormControl } from "react-bootstrap";
import QuickSearchSuggestions from "../QuickSearchSuggestions";

const QuickSearch = () => {
  const [isValid, setIsValid] = useState(false);
  const [searchQuery, setSearchQuery] = useState("");
  const handleChange = (value) => {
    const valueEntered = !!value;
    const isValid = valueEntered && value.length > 3;

    setIsValid(isValid);
    setSearchQuery(value);
  };

  return (
    <div className="justify-content-center d-flex position-relative">
                  
      <Form inline className="w-100">
                        
        <FormControl
          type="text"
          placeholder="Search entire shop"
          className="w-100"
          onChange={(e) => handleChange(e.target.value)}
        />
                    
      </Form>
                  
      <QuickSearchSuggestions isValid={isValid} searchQuery={searchQuery} />
              
    </div>
  );
};

export default QuickSearch;

I define two states there: isValid and searchQuery, and I pass them to the child component. I check the length of the value entered by a user in the search input, and if the length is higher than 3, I send the query.

Quick Search Suggestion component

Create a new component called QuickSearchSuggestion with the following content:

import React from "react";

import { ListGroup } from "react-bootstrap";
import PropTypes from "prop-types";
import useQuickSearchSuggestions from "../../hooks/useQuickSearchSuggestions";
import classes from "./QuickSearchSuggestions.module.css";

const QuickSearchSuggestions = (props) => {
  const { isValid, searchQuery } = props;
  const { hasSuggestions, isLoading, isOpen, items } =
    useQuickSearchSuggestions({ isValid, searchQuery });

  const suggestions = items.map((product) => {
    return (
      <ListGroup.Item key={product.id}>
                    {product.name}
                
      </ListGroup.Item>
    );
  });

  const shouldDisplaySuggestions = suggestions ? (
    <div className={classes.suggestions}>
              
      <ListGroup>
                    {suggestions}
                
      </ListGroup>
          
    </div>
  ) : null;

  if (isOpen && hasSuggestions) {
    return shouldDisplaySuggestions;
  } else if (isLoading) {
    return (
      <div className={classes.suggestions}>
                    <ListGroup.Item>Loading...</ListGroup.Item>
                
      </div>
    );
  } else if (isOpen && !hasSuggestions) {
    return (
      <div className={classes.suggestions}>
                    
        <ListGroup>
                          <ListGroup.Item>No products found</ListGroup.Item>
                      
        </ListGroup>
                
      </div>
    );
  } else {
    return null;
  }
};

QuickSearchSuggestions.propTypes = {
  isValid: PropTypes.bool.isRequired,
  searchQuery: PropTypes.string.isRequired,
};

export default QuickSearchSuggestions;

I use a custom hook there: useQuickSearchSuggestion. That hook's responsibility is to provide data and business logic for the component. I am going to define that hook in the next step.

To finish the QuickSearchSuggestion, I create a CSS module QuickSearchSuggestions.module.css with the following styles:

.suggestions {
    left: 0;
    position: absolute;
    top: 100%;
    right: 0;
    z-index: 10;
}

use Quick Search Suggestions custom hook

import { useEffect, useState } from "react";
import { useLazyQuery } from "@apollo/client";
import { GET_QUICK_SEARCH_SUGGESTIONS } from "../../queries/product.gql";
/**
 * The useQuickSearchSuggestions hook provides data and business logic for the QuickSearchSuggestions component
 *
 * @return {
 *  hasSuggestions {bool} - determines are products found based on provided search query
 *  isLoading {bool} - determines is data is currently loading
 *  isOpen {bool} - determines is component is opened
 *  items {array} - array with products returned from the API based on provided search query
 * }
 */
export const useQuickSearchSuggestions = (props) => {
  const { isValid, searchQuery } = props;
  const [isOpen, setIsOpen] = useState(false);
  const [hasSuggestions, setHasSuggestions] = useState(false);
  const [fetchSuggestions, { loading, data }] = useLazyQuery(
    GET_QUICK_SEARCH_SUGGESTIONS,
  );

  useEffect(() => {
    if (isValid) {
      fetchSuggestions({
        variables: {
          searchQuery,
        },
      });
      setIsOpen(true);
    } else {
      setIsOpen(false);
    }
  }, [fetchSuggestions, isValid, searchQuery]);

  useEffect(() => {
    data && data.products && data.products.items && data.products.items.length
      ? setHasSuggestions(true)
      : setHasSuggestions(false);
  }, [data]);

  return {
    hasSuggestions,
    isLoading: loading,
    isOpen,
    items:
      data && data.products && data.products.items ? data.products.items : [],
  };
};

export default useQuickSearchSuggestions;

As you can see, I've defined a lazy query that returns the fetchSuggestions function.

Then I use that function in effect. Before calling, I check if the search query is valid and update the isOpen flag. The fetchSugestions query function takes graphql variables (searchQuery), fetch the data, and returns it to the react component.

graphQL query

The last thing we need to do is create a graphQl query used by the useQuickSearchSuggestions hook.

export const GET_QUICK_SEARCH_SUGGESTIONS = gql`
    query getQuickSearchSuggestions($searchQuery: String!) {
        products(search: $searchQuery) {
            items {
                id
                name
                small_image {
                    url
                }
                url_key
                url_suffix
                price {
                    regularPrice {
                        amount {
                            value
                            currency
                        }
                    }
                }
            }
        }
    }
`;

Summary

It looks like the Quick Search functionality works good:

So to execute GraphQL queries using Apollo GraphQL client, you can choose between two custom apollo react hooks:

1. useQuery

2. useLazyQuery

What is the difference between useQuery hook and useLazyQuery?

When using useLazyQuery, it does not perform the associated query. Instead, the function returns query functions in the result tuples called when the query is executed.

The useLazyQery hook is perfect when you, for example, need to fetch data for the GraphQL server on user action, user clicking, or typing.

Apollo React Hooks and cached data

Apollo client provides a cache mechanism called InMemoryCache. Thanks to that, the apollo cache query results in memory. Of course, Apollo react hooks supports that cache. You can set the default fetch policy globally and locally on each query.

Handling GraphQL errors

Lazy query error handling is pretty the same as when you use the useQuery hook.

#WebDevelopment #FrontendDevelopment #JavaScript #React #GraphQL #ApolloClient #ReactBootstrap #Tutorial #ConceptExplanation #BestPractices #Intermediate #API

How many versions are there in Magento?

Usually, there is a division into two versions: Community (free version) and Enterprise (paid version). The enterprise version is not really called Magento anymore, but Adobe Commerce.

Adobe Commerce also offers the option of purchasing B2B modules (B2B for Adobe Commerce)

Regarding Magento Community, a fork of this version called Mage-OS is also available recently. It is a lightweight version of Magento maintained by the community.

In summary, there are versions of Magento available:

• Magento Community edition
• Mage-OS
• Adobe Commerce (Magento enterprise edition)
• B2B for Adobe Commerce

What is Magento Enterprise Edition?

Magento Enterprise Version is Magento's paid version. Comparing Magento community, Enterprise Edition provides enhanced customization features on other advanced features. Additional features include promotional pricing for a range of stores, product categories, and more.

Moreover, you can also use hosting services (Magento Cloud), technical support, and security support.

What is the difference between Magento CE and EE?

Community Edition is available free for Magento and does not charge additional for use. Enterprise Edition is available in Magento – costs are dependent on merchant sales. The higher the gross sales value of EE stores, the higher the fee is.

What features are available only in Magento 2 Enterprise Edition?

Magento enterprise edition offers many valuable features that can help sellers to provide the best shopping experience for their clients

Private sales

Thanks to private sales, you can create personalized shopping experiences, limited-time sales, or create a private sales page.

Gift Registry

Adobe Commerce gives your customers the ability to create gift registries for special occasions and to invite their friends and family to purchase their gifts from the gift registry.

Reward and Loyalty

Possibility to implement unique programs and promote customer loyalty.

Multiple wish lists

Magento community edition allows customers to have only one wishlist, but in the Magento enterprise edition, customers can have more than one wishlist.

Store credits

Magento enterprise edition offers customers to pay for products by using store credits.

Customer segmentation

In Magento 2 enterprise edition, there is an option to display content and promotion to specific customer accounts.

Customer attribute management

Enterprise edition allows administrators to manage customer attributes in the admin panel so that they can add custom attributes to the customer model.

Order management

Magento Commerce offers integration with Order Management System (OMS) Connector

Google tag manager

Magento enterprise edition allows configuring Google Tag manager, while the Magento community edition doesn't have a google tag manager module out-of-the-box.

How do I know if Magento is a community or enterprise?

Developers can easily check if a Magento enterprise edition or Community edition by inspecting the code or composer.json file. It's also possible to check the administration panel. If there are some features that are available only in the enterprise edition that means it is paid version

How much does Magento cost?

The cost of Magento is specific to the needs of a particular business and requires a bespoke quote. Total costs are calculated from your retail store average sales value, as well as annual online sales. It starts at around $22,000 a year and reaches $125,000. Licenses are yours.

Why is Magento so expensive?

Magento enterprise edition is a platform dedicated to large enterprise customers. Whether it is expensive is a subjective opinion. Magento will be expensive for some and not for others. I think that for customers considering Magento enterprise, price is not the most important factor.

What is the difference between the support of each version?

Magento community support includes support on Community Forums, Open Source, documentation, StackExchange, Reddit, Blogs, and many other groups. The official forum documentation can be found in Adobe Commerce. Despite this support, the Magento business edition has its own support. Magento commerce customers that paid for the license can, of course, count on support from Adobe.

What is the feature coverage of the Magento enterprise edition in headless solutions?

PWA Studio has little support for Magento enterprise features; Vue Storefront for Magento is integrated with the Magento community edition, so you won't find support for enterprise features there.

In both cases, you have to take custom development into account. You should also bear in mind that Magento GraphQL API does not support all enterprise features.

What is an alternative for Magento enterprise edition when I really want Magento?

Magento community edition is good for many clients, but Magento commerce offers many interesting features. So community vs enterprise edition is theoretically a hard choice, but not really at all when you start thinking about license cost. You may ask, is it worth the money? The answer is: it depends on your business! I think small businesses should consider the Magento community edition with some third-party solutions and modules from the marketplace that can cover missing Magento 2 enterprise edition features.

Conclusion

Magento community edition is a great proposition for small businesses, while Magento enterprise is a good solution for large players.

Magento enterprise is distinguished by additional features that are not available in the community version and support.

Resources

https://mage-os.org/

https://developer.adobe.com/commerce/webapi/rest/b2b/

https://business.adobe.com/pl/products/magento/features.html

#WebDevelopment #ECommerce #Magento #AdobeCommerce #PWAStudio #VueStorefront #ConceptExplanation #ToolComparison #TerminologyDefinitions #Intermediate

Nowadays, distributed architectures of software have become more popular, and along with the trend, software teams use the API-first approach to building products.

On the other hand, architects and developers decide to use the GraphQL API instead of REST more and more (but REST APIs are still good for sure)

I will not cite the well-known advantages and disadvantages of GraphQl here, but I want to stand the one that is not well-known but is quite important for developers:

One of the most significant advantages of using GraphQL is that a frontend developer can quickly mock sample data, and switch to real data when the backend is done.

What exactly is mock-up data?

Suppose some functionality needs data from the backend or somehow needs to communicate with the API, and this data is not available, or the API hasn’t been done yet. In that case, the Front-end developer needs to mock up some sample data. Take a look at the examples below:

1. Displaying additional information about a product

A development team is working on displaying additional information about a product on a product page. The data are called “Key features” and consist of an image, a name, and a description. This data will come from the backend. The backend team hasn’t started working on this functionality yet, so the Frontend developer decides to mock up this data and display this mockup on the front end. When the backend is done, the mockup data will be replaced with real data.

2. Sending a message to a seller

This functionality lets customers send a message to a seller. A customer fills out the form. He enters his name, surname, e-mail address, and message. Additionally, they must accept consent to the processing of personal data. The frontend developer has already built the form and validation and is at the stage of sending the form to the backend. The backend must pick up the form and return a success or error message, and this message will be displayed to the user. The backend part is not ready yet, so the Frontend developer needs to mock this interaction with the backend.

In summary, when some data like fields or even data collections have not been done yet in backend implementation, developers use fake values (mock data) and replace them with real data when the backend is ready.

In this article, I show how to mock:

• single fields

• queries

• mutation

In the end, I will show you how to easily replace mock data with real backend data.

With this knowledge, you will be able to work on your front end more efficiently, even when the back end is lagging far behind.

Prerequisites

Computer with a text editor, NodeJS, internet connection, basic JavaScript, React, and GraphQL skills.

Create react app

I use https://create-react-app.dev/docs/getting-started to scaffold a new project:

npx create-react-app graphql-mocks
cd graphql-mocks
npm start

Install Apollo Client

Next, I use the command line to install the apollo client:

npm install @apollo/client graphql

Apollo client allows connecting with GraphQL server and performing GraphQL operations like queries and mutations thanks to custom React hooks like useQuery or useMutation.

Initialize Apollo client

Once the client is installed, I can connect my front end with GraphQL API. This time I am going to use publically available https://api.spacex.land/graphql/.

First, I import Apolo Client, InMemoryCache, and ApolloProvider from @apollo/client.

import { ApolloClient, InMemoryCache, ApolloProvider } from "@apollo/client";

Second, I initialize the client:

const client = new ApolloClient({
  uri: "https://api.spacex.land/graphql/",
  cache: new InMemoryCache(),
});

That is the minimal config needed to make Apollo Client working - URL to API and in-memory cache initialized.

Third, I wrap the App component by ApolloProvider:

<ApolloProvider client={client}>
  <App />
</ApolloProvider>

ApolloProvided takes one argument: a client that we have already initialized. Once I wrap the App component with ApolloProvider, I can use the client in the App component and every child of the app component.

How to mockup single fields

In this example, I show you how to fetch existing fields from the API and how to add a field that doesn't exist in the response.

Create the missions component

In the beginning, I create the Missions component that will be responsible for displaying missions.

Create components \ missions \ Missions.jsx file:

export const Missions = () => {
  return (
    <>
      <h1>Missions</h1>
      Missions will be listed here
    </>
  );
};

Create components \ missions \ index.js file:

export { Missions } from "./Missions";

Create components \ index.js file:

export { Missions } from "./missions";

Import Missions component in the App.js:

import { Missions } from "./components";

Render component:

function App() {
  return (
    <main className="container">
      <Missions />
    </main>
  );
}

Add styles to App.css:

.container {
  max-width: 1200px;
  margin: 0 auto;
}

The query for the data

I want to fetch missions from the graphql server. To do so, I need to define a query.

I add file components \ missions\ missions.gql.js:

import { gql } from "@apollo/client";

export default gql`
  {
    missions(limit: 10) {
      description
      id
      manufacturers
      name
      twitter
      website
      wikipedia
    }
  }
`;

I import the query and useQuery hook in components \ Missions \ missions.jsx:

import { useQuery } from "@apollo/client";
import MISSIONS_QUERY from "./missions.gql.js";

I use the useQuery hookto fetch graphql data:

const { loading, error, data } = useQuery(MISSIONS_QUERY);

I add a little logic to handle loading and errors state:

if (loading) return null;
if (error) return `Error! ${error}`;
if (!data?.missions?.length) {
  return "No missions found";
}

const { missions } = data;

Finally, I render data returned from API:

{
  missions.map((mission) => {
    return (
      <div className="mission" key={mission.id}>
        <h2>{mission.name}</h2>
        <p>{mission.description}</p>
        <h3>Manufacturers:</h3>
        <ol>
          {mission.manufacturers?.map((manufacturer) => (
            <li key={`${mission.id}-${manufacturer}`}>{manufacturer}</li>
          ))}
        </ol>
        <h3>Links:</h3>
        <ul>
          {mission.twitter?.length && (
            <li>
              <a href={mission.twitter}>{mission.twitter}</a>
            </li>
          )}
          {mission.website?.length && (
            <li>
              <a href={mission.website}>{mission.website}</a>
            </li>
          )}
          {mission.wikipedia?.length && (
            <li>
              <a href={mission.wikipedia}>{mission.wikipedia}</a>
            </li>
          )}
        </ul>
      </div>
    );
  });
}

The complete code of the component looks like this:

import { useQuery } from "@apollo/client";
import MISSIONS_QUERY from "./missions.gql.js";

export const Missions = () => {
  const { loading, error, data } = useQuery(MISSIONS_QUERY);

  if (loading) return null;
  if (error) return `Error! ${error}`;
  if (!data?.missions?.length) {
    return "No missions found";
  }

  const { missions } = data;

  return (
    <>
      <h1>Missions</h1>
      {missions.map((mission) => {
        return (
          <div className="mission" key={mission.id}>
            <h2>{mission.name}</h2>
            <p>{mission.description}</p>
            <h3>Manufacturers:</h3>
            <ol>
              {mission.manufacturers?.map((manufacturer) => (
                <li key={`${mission.id}-${manufacturer}`}>{manufacturer}</li>
              ))}
            </ol>
            <h3>Links:</h3>
            <ul>
              {mission.twitter?.length && (
                <li>
                  <a href={mission.twitter}>{mission.twitter}</a>
                </li>
              )}
              {mission.website?.length && (
                <li>
                  <a href={mission.website}>{mission.website}</a>
                </li>
              )}
              {mission.wikipedia?.length && (
                <li>
                  <a href={mission.wikipedia}>{mission.wikipedia}</a>
                </li>
              )}
            </ul>
          </div>
        );
      })}
    </>
  );
};

Extend GraphQL schema on the client side

Here, the main topic of the article begins! The Missions component renders some data about missions on the front like description, name, web links and so on.

I want to mock one single field, which is a sponsors field, and it is an array of strings. To do so, I create the graphql-type-defs.js file in the root of the project with the following content:

import { gql } from "@apollo/client";

export default gql`
  extend type Mission {
    sponsors: [String]
  }
`;

That schema definition extends the Mission type and ads sponsors field to it.

Now I import my type definition in the index.js file:

import typeDefs from "./graphql-type-defs";

And pass it to the ApolloClient constructor:

const client = new ApolloClient({
  uri: "https://api.spacex.land/graphql/",
  cache: new InMemoryCache(),
  typeDefs,
});

Define a read function with mock data

The Next step is to define a custom read function to produce mock data for us.

Before I do that, I install FakerJS. it's a library (fake data generator) that helps produce fake and random data.

npm install @faker-js/faker --save-dev

Then, I pass the configuration with object types policies to the InMemoryCache constructor:

cache: new InMemoryCache({
    typePolicies: {
        Mission: {
            fields: {
                sponsors: {
                    read() {
                        return [...faker.random.words(faker.datatype.number({
                            'min': 1,
                            'max': 5
                        })).split(' ')]
                    }
                },
            },
        },
    },
}),

That code defines the read() function for the sponsors' field of the Mission type. The read() function returns fake objects. In this case, it returns a new array of from one to five elements. Elements in that array are random words.

Query with the @client directive and display data

To fetch the mock field, I need to add it to the query. To make it work, I need to use the @client directive. Take a look at the updated missions query:

export default gql`{
  missions(limit: 10) {
    description
    id
    manufacturers
    name
    twitter
    website
    wikipedia
    sponsors @client // here you go
  }
}
`;

Finally, I can render the sponsors field on the front end. I add this code to the render function of the missions component:

<h3>Sponsors:</h3>
<ol>
    {mission.sponsors?.map(sponsor => <li key={`${mission.id}-${sponsor}`}>{sponsor}</li>)}
</ol>

How to mockup an entire query

Mocking single fields is so useful. Moreover, sometimes devs want to mock a query or mutation that doesn't exist in the backend. Let's start by mocking a query.

Add a new query to the schema

Let's add the publications query that returns an array of publications (name of the publication and URL).

I extend the graphql-type-defs.js by adding new types:

type Query {
    publications: [Publication]
}

type Publication {
    name: String!
    url: String!
 }

Define resolver

Next, I need to define a resolver that will produce fake data for the publications query.

I create a graphql-resolvers.js file:

import { faker } from "@faker-js/faker";

export default {
  Query: {
    publications: () => {
      const publications = [];
      const publicationLength = faker.datatype.number({
        min: 1,
        max: 5,
      });

      for (let i = 0; i < publicationLength; i++) {
        publications.push({
          name: faker.lorem.sentence(),
          url: faker.internet.url(),
        });
      }
      return publications;
    },
  },
};

I defined the publications function that returns a new array of fake publications.

Register resolver

To register the resolver, you need to pass it to the ApolloClient constructor:

import resolvers from "./graphql-resolvers";

const client = new ApolloClient({
  uri: "https://api.spacex.land/graphql/",
  cache: new InMemoryCache({
    typePolicies: {
      Mission: {
        fields: {
          sponsors: {
            read() {
              return [
                ...faker.random
                  .words(
                    faker.datatype.number({
                      min: 1,
                      max: 5,
                    }),
                  )
                  .split(" "),
              ];
            },
          },
        },
      },
    },
  }),
  typeDefs,
  resolvers, // here you go
});

Use mocked query in the app

Let's create the publications component that displays mocked data.

components \ publications \ Publications.jsx

import { useQuery } from "@apollo/client";
// 1. here is imported the publications query
import PUBLICATIONS_QUERY from "./publications.gql.js";

export const Publications = () => {
  // 2. here the query is used
  const { loading, error, data } = useQuery(PUBLICATIONS_QUERY);

  if (loading) return null;
  if (error) return `Error! ${error}`;
  if (!data?.publications?.length) {
    return "No publications found";
  }

  const { publications } = data;

  return (
    <>
      <h1>Publications</h1>
      <ol>
        {publications?.map((publication) => (
          <li key={publication.name}>
            <a href={publication.url}>{publication.name}</a>
          </li>
        ))}
      </ol>
    </>
  );
};

(1.) I imported the publications query in this place, and here (2.) I used in it the useQuery hook.

As you can see from the component and useQuery hook perspective, it's not important if the quarry that is used is fake or real. It's transparent and works in the same way.

components \ publications \ publications.gql.js:

import { gql } from "@apollo/client";

export default gql`
  {
    publications @client {
      name
      url
    }
  }
`;

Directive @client allows defining not only fields like in the previous example but also queries and mutations.

components \ publications \ index.js:

export { Publications } from "./Publications";

components \ index.js:

export { Publications } from "./publications"; // added this import
export { Missions } from "./missions";

Add the publication component in the App.js:

import './App.css';
import {Missions, Publications} from "./components"; // added import

function App() {
  return <main className="container">
    <Missions/>
    <Publications/> !<-- added component -->
  </main>
}

export default App;

Ho to mock a graphql mutation

The last example I want to show is how to mock a graphql mutation. Let's implement a simple form that allows users to submit a new publication. The form has two inputs: the title of the publication and its URL.

Add the PublicationForm component

Create a file components \ PublicationForm \ PublicationForm.jsx

import { useCallback, useState } from "react";

export const PublicationForm = () => {
  const [title, setTitle] = useState("");
  const [url, setUrl] = useState("");

  const submitForm = useCallback(
    (e) => {
      e.preventDefault();
      console.log(title, url);
    },
    [title, url],
  );
  return (
    <form onSubmit={submitForm}>
      <legend>Submit a new publication:</legend>
      <input
        type="text"
        placeholder="Publication title"
        value={title}
        onChange={(e) => setTitle(e.target.value)}
      />
      <input
        type="text"
        placeholder="Publication URL"
        value={url}
        onChange={(e) => setUrl(e.target.value)}
      />
      <button type="submit">Submit</button>
    </form>
  );
};

So there are two fields in the form and the submit button. When a user clicks submit, the submitForm function is called. For now, it only logs to the console.

Create a file components \ publicationForm \ index.js

export { PublicationForm } from "./PublicationForm";

Re-export component in components/index.js:

export { Publications } from "./publications";
export { Missions } from "./missions";
export { PublicationForm } from "./publicationForm"; // added here

Add the component to the render function of the app component:

import "./App.css";
import { Missions, Publications, PublicationForm } from "./components";

function App() {
  return (
    <main className="container">
      <Missions />
      <Publications />
      <PublicationForm />
    </main>
  );
}

export default App;

Add the mutation to the schema

Let's define a new mutation in our graphql schema:

type Mutation {
  addPublication(name: String!, url: String!): String
}

The final graphql-type-defs looks like this:

import { gql } from "@apollo/client";

export default gql`
  extend type Mission {
    sponsors: [String]
  }

  type Query {
    publications: [Publication]
  }

  type Mutation {
    addPublication(name: String!, url: String!): String
  }

  type Publication {
    name: String!
    url: String!
  }
`;

Define a resolver for the mutation

Now, I am gonna add the addPublication mutation resolver to the graphql-resolvers.js file:

import { faker } from "@faker-js/faker";

export default {
  Query: {
    // query resolvers
  },

  Mutation: {
    addPublication: (parent, args, context, info) => {
      console.log(parent, args, context, info);
      return "Your publication has been submitted, thank you!";
    },
  },
};

I defined the mutation, and it returns a string. Of course, if you need more sophisticated testing of mocked mutation, you can add code here.

How to use mocked mutation in the app

Add components \ publicationForm \ addPublication.gql.js file:

import { gql } from "@apollo/client";

export default gql`
  mutation addPublication($name: String!, $url: String!) {
    addPublication(name: $name, url: $url) @client
  }
`;

As you can see, here also I used the @client directive to define mock mutation

Update the publicationForm.jsx component code:

import { useCallback, useMemo, useState } from "react";
import { useMutation } from "@apollo/client";
import ADD_PUBLICATION_MUTATION from "./addPublication.gql";

export const PublicationForm = () => {
  const [name, setName] = useState("");
  const [url, setUrl] = useState("");
  const [addPublication, { data, loading, error }] = useMutation(
    ADD_PUBLICATION_MUTATION,
  );

  const submitForm = useCallback(
    (e) => {
      e.preventDefault();
      addPublication({ variables: { name, url } });
    },
    [name, url, addPublication],
  );

  const results = useMemo(() => {
    return data?.addPublication;
  }, [data]);

  if (loading) return null;
  if (error) return `Error! ${error}`;

  return (
    <form onSubmit={submitForm}>
      <legend>Submit a new publication:</legend>
      <input
        type="text"
        placeholder="Publication title"
        value={name}
        onChange={(e) => setName(e.target.value)}
      />
      <input
        type="text"
        placeholder="Publication URL"
        value={url}
        onChange={(e) => setUrl(e.target.value)}
      />
      <button type="submit">Submit</button>
      <div>{results}</div>
    </form>
  );
};

Here I added the logic responsible for performing mutation. As for queries - it work the same with mocked mutation as with real ones.

How to use live data when it is ready

Ok, so we have mocked some fields, queries, and mutations, and you may ask what you should do when the backend team implements all requested fields and operations in the API.

It's pretty simple. You should:

1. 1. remove @client annotations - when a particular field or operation is ready, just remove the @client directive from query/mutation

2. 2. remove client resolvers - remove resolvers because they are not needed anymore when data is populated from API

3. 3. remove client type definitions - same here, the schema should be implemented on the backend side, so it's no need anymore

Summary

In this article, I showed you how to mock GraphQL queries and mutations. Compared to a REST API, mocking GraphQL queries is much easier. The subsequent transition to real data only really involves a change in GraphQL queries and resolvers’ removal. In my opinion, mocking data in GraphQL is much easier than in REST, which is unquestionably beneficial for everyone.

When you want to mock some fields or operations on the client side using Apollo Client, please follow these steps:

1. Create client-side GraphQL schema

2. Define custom resolvers/read function

3. Use @client directive in queries/mutations

I hope you liked this article. Thanks for reading!

#WebDevelopment #FrontendDevelopment #BackendDevelopment #ProgrammingFundamentals #JavaScript #GraphQL #React #Apollo #REST #Tutorial #DeepDive #BestPractices #ProjectSetup #Intermediate #APISecurity

GraphQL helps prevent the overloading of data. Unlike Restful API, GraphQL allows specifying fields that will be received from the server. That will result in faster communication and less traffic on the network, which will reduce response time considerably. There are two basic types of operations in GraphQL: queries and mutations.

For reading data, you use query, while for modifying data, you use mutation. The operation is a simple string that allows the server to parse and respond to the data in both cases.

What is a graphQL query?

Each GraphQL API has a GraphQL schema. The schema describes how data looks and which operations are allowed. So if you have a cars object in your schema, you would query for it. The graphQL query would look like this:

query getCars {
  cars {
    brand,
    color
  }
}

In the above example, you can see a single graphQL query named getCars. In that GraphQL operation, there is the query defined that fetches two fields of cars type: brand and color. I will show you more details about GraphQL queries in this article, but first, let's see how it's possible to execute queries and consume any GraphQL API.

Prerequisites

In this article, I would like to show you two common things: using a GraphQL query on the client side and writing a basic query using NodeJS.

GraphQL API

For the first case, you don't need your GraphQL API. You can use some public GraphQL APIs to experiment.

A well-built API to start practicing with is the SpaceX API: https://api.spacex.land/graphql/

Graphql server

In case when you want to create your GraphQL API(with queries), you need to create a GraphQL server. I am going to show you a straightforward example built using Node and ExpressJS.

Where do you run a query in GraphQL?

Let's start by consuming SpaceX API to learn fundamentals about graphQL queries. You have at least four options to play with that API:

• using GraphQL Playground

• using GraphiQL Explorer

• using Apollo Studio

• using Chrome extensions like Altair GraphQL

GraphQL Playground & GraphiQL Explorer

Those are tools that allow you to play with every graphQL API. For example, when you put this URL in the browser: https://api.spacex.land/graphql/ you will see GraphiQL explorer. There you can inspect schema, read the docs, run queries, mutations, and so on. GraphQL playground has pretty much the same set of features.

You can set up a playground on the project level or install it for macOS App.

Note: GraphQL Playground and GraphiQL are joining forces. More info here: https://github.com/graphql/graphql-playground/issues/1143

Apollo Studio

In case when you are creating your graphQL server using https://github.com/apollographql/apollo-server, you will be able to use Apollo Studio to inspect your API.

Altair GraphQL Client

Altair client is a Chrome extension that allows you to inspect GraphQL spec, query for all the data, send mutations, use subscriptions, etc.

Today I will use GraphiQL API because the SpaceX API provides it. Typically, you will use tools that are provided with the project/graphQL servers. If you develop your project, you are comfortable to choose own Playground, but this does not matter because soon, both tools will be merged.

Chrome extension is a good choice if you want to check sometimes fast and don't have a chance to use any Playground, but in general, you can use that extension and don't use playgrounds. All of those technics are good enough.

The query for the data

Theory, theory, theory.... let's stop with that and get our hands dirty!

Let's try to get to all users!

{
  users {
    name
    rocket
  }
}

How simple is that?

In the above example, you can see a simple query. The 'users' objects can be used to request data about all available users – 'users' is an object in GraphQL terms. Objects hold data about an entity. Each object has fields. We used the name and rocket field in our case, but there are more fields for the users' objects. Take a look at the docs:

id: uuid!
name: String
rocket: String
timestamp: timestampt!
twitter: String

Some fields cannot be empty (null), and an exclamation mark determines it at the end. That means that, for example, the id cannot be null or undefined. If will be, GraphQL will throw an error.

The results of the following query may look like this:

{
  "data": {
    "users": [
      {
        "name": "sherlock holmes",
        "rocket": "221B Baker Street"
      },
      {
        "name": "sherlock holmes",
        "rocket": "221B Baker Street"
      },
      {
        "name": "sherlock holmes",
        "rocket": "221B Baker Street"
      },
      {
        "name": "sherlock holmes",
        "rocket": "221B Baker Street"
      },
      {
        "name": "User_14211338",
        "rocket": "Space_101010101"
      },
      {
        "name": "Elanthamil",
        "rocket": "Elanthamil"
      }
    ]
  }
}

Congratulations! You made your first graphQL query! You are well on your way to becoming a GraphQL master, really!

Query with variables

In the previous example, you have seen a straightforward query (anonymous operation). Now we are going to do something more complicated, like a query with variables. When you want to pass a variable to a graphQL query, you can pass them as parameters:

{
  users(limit: 10, order_by: {name: asc}) {
    name
    rocket
  }
}

That works in Playground, but it's not too valuable because the values of variables are hardcoded. Let's define a named query using (surprising) a query keyword:

query getUsers($limit: Int, $orderBy: [users_order_by!]) {
  users(limit: $limit, order_by: $orderBy) {
    name
    rocket
  }
}

As you can see here, we have passed two variables: $limit, which is a type of Int, and $orderBy, which is a type of [users_order_by!].

Types can be primitive like String, Int, Float, Boolean, and ID, and also you can declare custom types in the https://marcin-kwiatkowski.com/blog/graphql/introduction-to-the-apollo-local-state-and-reactive-variables schema.

An exclamation mark means that this parameter cannot be empty. You have a special place called "Query variables" (at the bottom). It will help if you put a query variable there. Otherwise, the query will throw an error.

You can also specify a default variable in GraphQL. It works only for non-required arguments. Take a look:

query getUsers($limit: Int = 5, $orderBy: [users_order_by!]) {
  users(limit: $limit, order_by: $orderBy) {
    name
    rocket
  }
}

Nested objects

You can request nested fields in a query (based on graphQL schema):

query getLaunchesPast($limit: Int = 2) {
  launchesPast(limit: $limit) {
    mission_name
    launch_date_local
    launch_site {
      site_name_long
    }
    rocket {
      rocket_name
      first_stage {
        cores {
          flight
          core {
            reuse_count
            status
          }
        }
      }
    }
  }
}

The results may look like this:

{
  "data": {
    "launchesPast": [
      {
        "mission_name": "Starlink-15 (v1.0)",
        "launch_date_local": "2020-10-24T11:31:00-04:00",
        "launch_site": {
          "site_name_long": "Cape Canaveral Air Force Station Space Launch Complex 40"
        },
        "rocket": {
          "rocket_name": "Falcon 9",
          "first_stage": {
            "cores": [
              {
                "flight": 7,
                "core": {
                  "reuse_count": 6,
                  "status": "unknown"
                }
              }
            ]
          }
        }
      },
      {
        "mission_name": "Sentinel-6 Michael Freilich",
        "launch_date_local": "2020-11-21T09:17:00-08:00",
        "launch_site": {
          "site_name_long": "Vandenberg Air Force Base Space Launch Complex 4E"
        },
        "rocket": {
          "rocket_name": "Falcon 9",
          "first_stage": {
            "cores": [
              {
                "flight": 1,
                "core": {
                  "reuse_count": 0,
                  "status": null
                }
              }
            ]
          }
        }
      }
    ]
  }
}

Directives

Directives let you perform a conditional query for objects. There are two types of directives: include and skip. You can pass a bool variable to the query and then use this variable in the directive. Take a look at how it works:

query getLaunchesPast($limit: Int = 2, $withRockets: Boolean = false) {
  launchesPast(limit: $limit) {
    mission_name
    launch_date_local
    launch_site {
      site_name_long
    }
    rocket @include(if: $withRockets) {
      rocket_name
      first_stage {
        cores {
          flight
          core {
            reuse_count
            status
          }
        }
      }
    }
  }
}

Note: Unfortunately, SpaceX API uses an older version of GraphQL tools, and those directives are not supported there.

Note 2: GraphQL Server implementations may also add experimental features by defining completely new directives.

How do GraphQL queries work?

When you want to send a query from the front end, a single request comes to the graphQL server. GraphQL takes a query and looks at what you need, and then a resolver function gets all related data and returns a JSON object.

Theoretically, you can send a request as a simple HTTP request, but a good practice is to use one of the GraphQL clients to communicate with a server. Honestly, in real projects, you have to use the GraphQL client on the front end because it brings a lot of advantages like caching, mechanisms for sending queries, mutations, and so on.

How do I create a query in GraphQL?

I showed you how to send a query. Now let's create our GraphQL server and define a query.

We are going to use NodeJS and Apollo Server to scaffold an app.

The app is a big word. It will be basic stuff. Let's create a query that returns Hello World. It is a fantastic idea, isn't it?

Set-up a project

Let's init a new project by npm init command. Then please install all necessary dependencies**:**

npm install apollo-server graphql --save

Create an index.js file

Create an index.js file in the src directory(create the directory as well).

Put these imports at the beginning of the file:

const { ApolloServer, gql } = require("apollo-server");

Create schema

Let's create theschema. We have to make two types:

1. The Query type with welcomeMessage query

2. The Message type is an object that represents our Message. It has only one field: text which cannot be empty.

Put this code to the file:

const typeDefs = gql`
  type Query {
    welcomeMessage: Message!
  }

  type Message {
    text: String!
  }
`;
10;

Create resolver

It's time to create a resolver function for the welcomeMessage query. In real projects, resolvers communicate with databases or other data and collect data. In our trivial example, we want to return a hardcoded string.

Here you go:

const resolvers = {
  Query: {
    welcomeMessage: () => {
      return {
        text: "Hello World",
      };
    },
  },
};

Initialize server

The last thing is to create a server instance:

const server = new ApolloServer({
  typeDefs,
  resolvers,
});

server.listen().then(({ url }) => {
  console.log(`🚀 Server ready at ${url}`);
});

You can run that server by typing node ./src/index.js in the console.

Now you can see something like this:

Summary

I hope you enjoyed our quick tour through GraphQL queries. Let me summarize:

• GraphQL has two basic types of operations: queries and mutations

• queries read data. Mutations write data

• there are a few ways to consume or inspecting GraphQL API, like playgrounds and Browser extensions

• graphQL query can be anonymous or can have a name

• you can pass variables to a query

• query variable can have a default value

• each returned field can have a nested object with other data

• There are predefined directives like @include and @skip, and also you can write your directives on the server side.

• To create your graphQL server, you can use Node and Apollo servers.

• Of course, you can even use PHP to write an apollo server, but who wants to write code in PHP?

That essential information should help you to understand the basics of graphQL queries.

#WebDevelopment #BackendDevelopment #API #JavaScript #NodeJS #GraphQL #Apollo #REST #ExpressJS #ConceptExplanation #Tutorial #DeepDive #Intermediate

• operation level

• application level

Operation-level errors handling

In this case, you have access to the data, loading, and error fields, and you can use an error object, which can be used to show a conditional error message.

const { loading, error, data } = useQuery(YOUR_QUERY);

if (error) return <p>Error :(</p>;

Of course, you can create a component responsible for displaying errors in your app.

import React from "react";
import PropTypes from "prop-types";

import classes from "./ErrorMessage.module.css";

const ErrorMessage = (props) => {
  const { error, ...rest } = props;

  const shouldDisplayError =
    error && error.message ? (
      <div className={classes.errorMessage} {...rest}>
        {error.message}
      </div>
    ) : null;
  return shouldDisplayError;
};

ErrorMessage.propTypes = {
  error: PropTypes.shape({
    message: PropTypes.string.isRequired,
  }),
};

export default ErrorMessage;

This component is really straightforward. It receives an error as a prop and displays that error to the user.

Application-level error handling

Another approach is handling errors in Application-level. It allows you to create more complex logic.

Application-error handling lets you do whatever you want with errors. For example, you can log those errors to the console in development mode or use external tracking error tools like Sentry on production.

You can use this mechanism to display messages to the user as well. Let’s imagine that you have Messages Context in your app or you have a custom hook, and there you keep the whole logic for adding/removing/displaying messages.

If you use application-level error handling, you can pass error messages to your messages/notification manager and do whatever you want with them.

There are two types of errors.

1. GraphQL errors (like in a previous example)

2. Network error (for example, if the app lost internet connection)

GraphQL errors

There are three types of GraphQL errors:

• syntax error - for example, when you made a mistake in a query or mutation

• resolver error - for example, when the GraphQL server was not able to resolve a query field

• validation error - for example, when provided data didn't pass validation on the server side.

Note that when there is a resolver error, the GraphQL server returns partial data, but if there is a syntax or validation error, the server doesn't return data at all.

In the first case, the server responds with a 200 status code, otherwise returns a 4xx status code (for syntax and validation errors)

Network errors

Network errors occur when there are communication problems with the GraphQL server. In this case, the server usually responds with a 4xx or 5xx response status code and no data.

Error policies

By default, the Introduction%20to%20the%20Apollo%20local%20state%20and%20reactive%20variables.md server returns partial data when there is a resolver error, but you can change this behavior by changing the error policy. There are three error policies:

• none - the default one - if there are errors the graphQLErrorsthe field is populated and the data field is set to undefined (even if the server returns some data in response)

• all - both fields data and graphQLErrors are populated

• ignore - graphQLErrorsfield is ignored and not populated

How to specify error policy

You can specify error policy globally on or query/mutation level.

Global error policy

You can set an error policy for queries and mutations using the defaultOptions object in the ApolloClient constructor. The example below shows an error policy all set for queries and an ignore policy for mutations.

import { ApolloClient, InMemoryCache } from "@apollo/client";

const client = new ApolloClient({
  cache: new InMemoryCache(),
  uri: "http://localhost:3000/",
  defaultOptions: {
    query: {
      errorPolicy: "all",
    },
    mutate: {
      errorPolicy: "ignore",
    },
  },
});

Operation error policy

To specify error policy on the operation level, you have to pass the errorPolicy field in options object like this:

const { loading, error, data } = useQuery(YOUR_QUERY, {
  errorPolicy: "ignore",
});

Implement application-level error handling

To implement application-level error handling, we need to use a functionality called ApolloLink.

The Apollo Link library helps you customize the data flow between Apollo Client and your GraphQL server. You can define your client's network behavior as a chain of link objects that execute in a sequence.

Each link should represent either a self-contained modification to a GraphQL operation or a side effect (such as logging).

Take a look at a sample implementation of application-level error handling.

First, import the onError function.

import { onError } from "@apollo/client/link/error";

Second, create the errorLink:

const errorLink = onError(({ graphQLErrors, networkError }) => {
  if (graphQLErrors) {
    console.log(graphQLErrors);
  }

  if (networkError) {
    // handle network error
    console.log(networkError);
  }
});

Third, use HttpLink, and from helper method to combine a single link that can be used in the Apollo client.

import { ApolloClient, InMemoryCache, ApolloProvider, from, HttpLink } from '@apollo/client';

...

const httpLink = new HttpLink({ uri: 'https://<API_URL>' })

const appLink = from([
    errorLink, httpLink
])

const client = new ApolloClient({
    link: appLink,
    cache: new InMemoryCache(),

});

Summary

There are two types of errors that you can handle:

1. network errors

2. GraphQL error

There are three error policies (all, ignore, and none), and you can specify an error policy globally or on the operation level.

Moreover, there are two levels where you can handle those errors:

1. application level

2. component (query/mutation) level

Thanks to application-level error handling, you can use JavaScript error tracking tools on production and log errors to the console in local environments. Besides, you can use this mechanism to handle and display errors in your application.

#WebDevelopment #FrontendDevelopment #BackendDevelopment #JavaScript #React #GraphQL #ApolloClient #ConceptExplanation #Tutorial #BestPractices #Intermediate #ErrorHandling #APIIntegration

GraphQL has become one of the most popular APIs for building web applications. It gives many benefits for frontend development:

• query language and the possibility to get precisely that data from the backend that you need

• one endpoint for everything

• self-documented API operations

• validation out-of-the-box

Magento 2 has supported GraphQL for a while, and in the case of creating a headless storefront, GraphQL API is a perfect choice. I want to show you the benefits of using GraphQL API and how to work with it, and at the end, I will show you some example queries that fetch some basic eCommerce stuff like categories, products, cms pages, and carts.

Magento 2 API: What's new?

The main problem with GraphQL in Magento when it was introduced that developers met was the lack of supported Magento features. Magento itself has a massive amount of fantastic features, and it's essential to have as many of them as possible supported in API. Of course, it's an option to use REST API in some places instead of GraphQL, but it is not a perfect solution.

Anyway, Adobe and Magento community have been working hard to improve and develop Magento GQL API. They have recently added many new supported features related to a customer, my account, and b2b functionalities.

On the other hand, module vendors started providing custom GraphQL queries and notations as a part of the custom GraphQL module. In case when an extension does not has GraphQL support, implementing GraphQL operations is still an option because Magento 2 API is extensible.

GraphQL compared to REST API

I won't elaborate on the difference between GraphQL API and REST API (or even with soap API) because there are many great articles about that on the web. Still, I want to focus on GraphQL benefits from a frontend perspective. Read the below paragraphs to see more details.

Query language and Graphql schema

When you want to fetch some data from GraphQL API, you basically need to specify what data you need. To do so, you inspect the GraphQL schema and choose what you will query about.

For example, in Magento, there is a categoryList GraphQL query that returns an array containing information about the category. There are a lot of fields, and depending on the situation and your needs, you select whatever you want, for example, UID of category and name:

query getCategories(
    $filters: CategoryFilterInput,
  ) {
    categoryList(filters: $filters) {
      uid
      name
  }
}

// variables passed to the query:

{
  "filters": {
    "url_path": {
      "eq": "gear/bags"
    }
  }
}

// results:
{
  "data": {
    "categoryList": [
      {
        "uid": "NA==",
        "name": "Bags"
      }
    ]
  }
}

Here you can see the schema definition for the categoryList query:

Of course, there are more fields, but they are out of the screenshot, sorry 😆

One endpoint

The next advantage of GraphQL is one endpoint for all requests. In REST API, each request has a different URL, and in addition, each URL can have multiple behaviors depending on the HTTP method like POST, GET, PUT, and so on.

GraphQL haters can say that it's not a problem. I agree it's not a problem, but let's explain that to frontend developers 😂

Using GraphQL is relatively easier for frontend developers than using REST API because everything is in one place, in one endpoint and even calling API is simpler because you have to change only the payload you send to API.

Multiple resources at the same time

In REST API, when you want to fetch multiple resources, for example, categories and products, you need to send requests to various endpoints. This complicates implementation and decreases performance because each millisecond count and each HTTP request increase communication time with APIs in the Core Web Vitals world.

Using GraphQL, you can fetch multiple resources in one query, so it's not a problem to fetch products and categories simultaneously, and it's not even a problem to fetch a cart as well.

Validation

GQL provides schema validation OOTB, so if you send a wrong request, you miss some variables, and you will see meaningful errors. For example, if you query for a field that doesn't exist, https://marcin-kwiatkowski.com/blog/graphql/2-ways-of-handling-graphql-errors-in-apollo-client will inform you that the field you requested does not exist.

No more over-fetching

REST API typically returns a wall of data, and in most cases, 98% of data returned from REST API is redundant on the front. This dramatically increases the size of HTTP calls and decreases performance.

Well designed application that consumes GraphQL API fetches only that data that is needed in UI, so you get what you need, and the size of API calls is smaller

How to connect with Magento2 GraphQL API

To connect with Magento 2 GraphQL API, you must send a request to the GraphQL endpoint. Typically is /graphql.

You can use some of the GraphQL playgrounds or browsers extensions to test GraphQL API and send some queries and mutations. I use https://chrome.google.com/webstore/detail/altair-graphql-client/flnheeellpciglgpaodhkhmapeljopja?hl=en chrome extension

Extensions like that are compelling and allow you to send graphql queries, mutations, set variables, HTTP headers, and read schema documentation so testing each GraphQL API is easy.

Magento GraphQL endpoint HTTP headers

There is one crucial thing about sending GraphQL requests: the possibility of changing the response by adding specific HTTP headers.

Magento 2 GraphQL API and Multistore

When you have configured Multistore in the Magento backend, you can fetch data for different store views by passing the Store HTTP header.

Imagine that you have two store views: default and german, and those store views have set up different languages: English for the default store view and german for the german store. If you wanted to send a query for categories, you would have to use a graphQL query like this:

{
  categoryList {
      uid
      name
      url_key
      children {
        uid
        name
        url_key
      }
  }
}

The possible response can look like this:

{
  "data": {
    "categoryList": [
      {
        "uid": "Mg==",
        "name": "Default Category",
        "url_key": null,
        "children": [
          {
            "uid": "Mzg=",
            "name": "What's New",
            "url_key": "what-is-new"
          },
          {
            "uid": "MjA=",
            "name": "Women",
            "url_key": "women"
          },
          {
            "uid": "MTE=",
            "name": "Men",
            "url_key": "men"
          },
          {
            "uid": "Mw==",
            "name": "Gear",
            "url_key": "gear"
          },
          {
            "uid": "OQ==",
            "name": "Training",
            "url_key": "training"
          },
          {
            "uid": "Mzc=",
            "name": "Sale",
            "url_key": "sale"
          }
        ]
      }
    ]
  }
}

Assuming you have translated category names for the german store, you have just to set Store header equals 'german' to fetch categories for the german store. You would see categories for a german store below.

{
  "data": {
    "categoryList": [
      {
        "uid": "Mg==",
        "name": "Default Category",
        "url_key": null,
        "children": [
          {
            "uid": "Mzg=",
            "name": "Was gibt's Neues",
            "url_key": "what-is-new"
          },
          {
            "uid": "MjA=",
            "name": "Frau",
            "url_key": "women"
          },
          {
            "uid": "MTE=",
            "name": "Männer",
            "url_key": "men"
          },
          {
            "uid": "Mw==",
            "name": "Ausrüstung",
            "url_key": "gear"
          },
          {
            "uid": "OQ==",
            "name": "Ausbildung",
            "url_key": "training"
          },
          {
            "uid": "Mzc=",
            "name": "Sale",
            "url_key": "sale"
          }
        ]
      }
    ]
  }
}

Remember that the query is the same so passing a Store header to requests allows you to fetch data for different stores. Magento multistore is mighty to have different categories, products, prices, languages, and cms content for different store views.

Graphql queries in Magento and currency

Price and currency are an essential part of each eCommerce platform because the product has prices, brands typically operate in different markets and different countries, and allow to buy products in other currencies. Luckily, GraphQL in Magento will enable you to fetch different prices for different stores with different currencies.

Fetch available currencies data from Magento 2

You can set available currencies for each store view in the Magento backend panel. To do so, log in as an administrator and go to Stores -> Configuration -> General -> Currency Setup. There you can see Allowed Currencies multi-select. When you uncheck the "Use system value" checkbox, you will be able to select available currencies for the selected store view.

The next step is to fetch those currencies to display the currencies switcher on the storefront.

To do that, use the currency graphql query:

{
  currency {
        available_currency_codes
    }
}

In my demo store it returns these results:

{
  "data": {
    "currency": {
      "available_currency_codes": ["EUR", "PLN", "USD"]
    }
  }
}

When you need to fetch available currencies for other store views, you must again set the Store HTTP header (as in the example with categories that I have shown you earlier).

Fetch correct prices for the selected currency

Based on available currencies data, it's easy to implement a currency switcher on a storefront and add the possibility for customers to select a currency. When customers choose a different currency than the default one, we have to send that information to Magento.

There is the Content-Currency HTTP header, and if it's passed to the GraphQL endpoint, Magento will return prices in the specified currency. For example, let's fetch some products from Magento:

query getProductsForCategory(
    $filter: ProductAttributeFilterInput,
  $productsPageSize: Int = 10,
   $currentProductsPage: Int = 1
  ) {
    products(filter: $filter, pageSize: $productsPageSize, currentPage: $currentProductsPage) {
      items {
        uid
        name
        price_range {
          maximum_price {
            final_price {
              currency
              value
            }
            regular_price {
              currency
              value
            }
          }
          minimum_price {
            final_price {
              currency
              value
            }
            regular_price {
              currency
              value
            }
          }
        }
      }
  }
}

Let's fetch just one product for one of the categories. I want to use the Bags category that has UID equals NA==. Variables that I pass to query look like this:

// variables
{
  "filter": {
    "category_uid": {
      "eq": "NA=="
    }
  },
  "productsPageSize": 1
}

For that query and variables, Magento returns this data for me:

{
  "data": {
    "products": {
      "items": [
        {
          "uid": "MTQ=",
          "name": "Push It Messenger Bag",
          "price_range": {
            "maximum_price": {
              "final_price": {
                "currency": "USD",
                "value": 45
              },
              "regular_price": {
                "currency": "USD",
                "value": 45
              }
            },
            "minimum_price": {
              "final_price": {
                "currency": "USD",
                "value": 45
              },
              "regular_price": {
                "currency": "USD",
                "value": 45
              }
            }
          }
        }
      ]
    }
  }
}

As you can see, the returned currency is USD (because it is the default one), and prices are in USD. Now I set the Content-Currency HTTP header to EUR, and Magento will return prices in EUR. Take a look at the below code:

{
  "data": {
    "products": {
      "items": [
        {
          "uid": "MTQ=",
          "name": "Push It Messenger Bag",
          "price_range": {
            "maximum_price": {
              "final_price": {
                "currency": "EUR",
                "value": 31.8
              },
              "regular_price": {
                "currency": "EUR",
                "value": 31.8
              }
            },
            "minimum_price": {
              "final_price": {
                "currency": "EUR",
                "value": 31.8
              },
              "regular_price": {
                "currency": "EUR",
                "value": 31.8
              }
            }
          }
        }
      ]
    }
  }
}

Authorization with Magento 2 GraphQL

Another crucial thing relates to HTTP headers is Authorization. When you want to fetch content available only for logged-in users, like customer data, you must set the Authorization HTTP header. Then Magento will return that data. Otherwise, graphQL queries without that header will return validation notice that the customer isn't authorized to fetch data specified in a request.

How to optimize Magento 2 GraphQL endpoint

Magento haters say that Magento GQL API is slow, but I must disagree with that. Maybe it is not the fastest on the market, but there are several options to optimize each request.

To optimize Graphql endpoints, I recommend using Varnish and changing the HTTP method for graphql queries from POST to GET. Then you can cache several queries and reduce the time of response twice or even more!

Varnish caching example

Here you have the query that fetches 20 products from Magento without Varnish caching:

Response time is 311ms when response time with Varnish is only 96ms for the same query!

Conclusion

Magento GQL is an API that allows you to fetch data from Magento using queries and save information in Magento using mutations. If you would experiment with Magento 2 GraphQL, you have to set up the Magento store or use one of the public available Magento demos, then use one of the GraphQL Clients or Chrome extensions like Altair GraphQL client. You can use Postman as well.

Magento 2 has excellent support in GraphQL API for its features and advantages compared to REST architecture. Hence, it's a perfect choice when you want to fetch required data in your headless storefront.

GraphQL and headless

Nowadays, the most popular headless storefronts and boilerplates like Vue Storefront and PWA Studio use GraphQL API to communicate with Magento. Besides, Extensions providers for Magento 2 have started adding support for GraphQL in their extensions. That all can mean that headless storefronts, composable commerce, and all pretty new things will constantly be developing near future!

#WebDevelopment #BackendDevelopment #FrontendDevelopment #eCommerce #JavaScript #GraphQL #Magento #REST #Apollo #ConceptExplanation #Comparison #BestPractices #TechnicalOverview #Intermediate #API #PerformanceOptimization #Scalability

A Guide to React Context and useContext() hook

React Context gives data about the components regardless of the level of the component tree. The Context allows managing global data, such as global theme services, user preference, notifications, or more.

On the other hand, you can have Contexts for each more significant part of your app. In case you create an eCommerce react app, you can have Context for cart, the Context for account pages, checkout, and so on.

Context provides data and methods for child components, so the cart needs data about products in the cart. It offers methods to manipulate a cart like adding items, removing, applying discount codes, etc.

I like React because we can find many different solutions for different issues. We have a couple of varying form libraries, lots of CSS libraries, and we have several libraries specifically geared towards state data problems in React. It can be learned by experience in using the library in your project. Sometimes we may install and use libraries that we do not need.

The same is with the state management library. You can use external ones, or you can use context API. It's up to you! It would help if you thought three times before installing any state management library because Context solves issues well in typical cases.

Why Context API?

React enables us to assemble reusable applications with components to repurpose the applications we create. So the React application contains several elements. When an application is rolled out, these components are often significant and unmaintained, which is why we divide them into small parts. This is a fascinating concept in React — you can have lots of components and have an efficient and concise application without having a significant component. When breaking down smaller components for maintenance purposes, they might need a little more data to work correctly.

Use of provider pattern in React

You probably know about the prop drill. As part of developing an application, you will probably find yourself attempting to drill down layers of components. We have to send props across different levels of components to make them available.

To summarize, prop drilling is a situation when you have to pass down props to a child component, and then to another child, and another.

Context provides a way to avoid props drilling

Take a look at the example:

import React, { useState } from "react";

export const Account = () => {
  const [user, setUser] = useState({ name: "Marcin", country: "Poland" });

  <AccountDetails user={user} setUser={setUser} />;
};

export const EditAccount = (props) => {
  const { user, setUser } = props;

  return (
    <form>
      <input
        type="text"
        value={user.name}
        onChange={(e) =>
          setUser({
            ...user,
            name: e.target.value,
          })
        }
      />

      <input
        type="text"
        value={user.country}
        onChange={(e) =>
          setUser({
            ...user,
            country: e.target.value,
          })
        }
      />
    </form>
  );
};

export const AccountDetails = (props) => {
  const { user, setUser } = props;

  return (
    <>
      <h1>{user.name}</h1>
      <p>Country: {user.country}</p>

      <EditAccount user={user} setUser={setUser}></EditAccount>
    </>
  );
};

The Account component passes props user and SetUser to the account details component, and AccountDetailsComponent passes them to the EditAccount component.

Prop drilling, also called threading, is a good and helpful pattern, besides in some cases, you want to avoid using it. Let's consider when you have a notification system in your app. There are two available methods:

1. addMessage

2. removeMessage

You want to have the opportunity to use those methods in any component that you want.

Parent component -> consuming components communication

To fix the problems with prop drilling, the global object must be accessible in the react tree directly by the components in the tree. React Context is a useful mechanism that allows you to pass data through each child component without prop drilling. React Context can help you a lot.

Note: using Context in some components makes them depend on that Context. Please remember that when you are architecting your app.

Creating Context

To create Context, you have to use react createContext method:

export const MessagesContext = createContext();

Providing data to a Context

Any Context object has its Provider component that allows passing data to the Context.

To pass data to the Provider component, you need to use value prop:

<MyContext.Provider value={<value here>}>

Take a look at the real example:

import React, { createContext, useReducer } from "react";

import {
  MessagesReducer,
  messagesInitialState,
  addMessage as addMessageAction,
  removeMessage as removeMessageAction,
} from "../../reducers/Messages";

export const MessagesContext = createContext();

export const MessagesProvider = ({ children }) => {
  const [{ messages }, dispatch] = useReducer(
    MessagesReducer,
    messagesInitialState,
  );

  const removeMessage = (message) => dispatch(removeMessageAction(message));

  const addMessage = (message) => dispatch(addMessageAction(message));

  return (
    <MessagesContext.Provider
      value={{
        messages,

        addMessage,

        removeMessage,
      }}
    >
      {children}
    </MessagesContext.Provider>
  );
};

That Context uses the useReducer hook for state management and returns Provider with messages array, and two methods: addMessage and remove message.

Injecting Context to an App

To inject your Context into an App, you need to wrap your app by the Provider component. Typically index.js or app.js file is the best place to do this:

import { MessagesProvider } from "./contexts/Messages";

const App = () => {
  return (
    <MessagesProvider>
              
      <Router>
                    
        <>
                          
          <PageHeader />
                          
          <Messages />
                          
          <Switch>
                                
            <Route path="/category/:categoryUrlKey" component={CategoryRoute} />
                                
            <Route path="/product/:productUrlKey" component={ProductRoute} />
                            
          </Switch>
                      
        </>
                
      </Router>
          
    </MessagesProvider>
  );
};

Using React Context in components with useContext hook

React hooks enable us in functional components to store the state data. React has some hooks that are included. UseState, UseCallback, UseEffects and others. The other thing which we want to discuss in detail is useContext hook. UseContext hooks allow you to connect and consume contexts. This hook uses an argument that contains the Context of your choice. Then, you can access the context value.

The last thing I want to show you is using Context in child components.

We exported two things from the file where we declared Context:

1. MessagesContext

2. MessagesProvider

We used MessagesProvider to wrap the App component. At the same time, MessageContext references our Context, and we have to pass it as an argument to the useContext hook in the component when we want to use that Context.

import { MessagesContext } from '../../contexts/Messages';
const Messages = () => {

    const { messages, removeMessage, addMessage } = useContext(MessagesContext);
    (...)
};

Now we can use all Context data in our component.

Summary

React Context API provides another way to pass data to multiple components and be more precise: to all the children of Context components. The context object provides data and methods to a consumer component, and a consumer reads context value.

Alternatively, without react's Context, you can pass props down manually to each react component, but in this case, you will meet a "props drilling" problem. React's context API allows to avoid prop drilling, but on the other hand – it adds dependency between react components and Context.

Moreover, testing a react component that consumes context value is a bit more complicated, but it is, of course, double, and there are a few patterns to do that. Anyway, using Context is an option for state management in react projects instead of installing external state management libraries.

Complete set up of context API includes:

1. Create Context by using react createContext method

2. Create context provider by using the Provider react component

3. Inject context provider to the component tree

4. Consume Context in the following components by using the useContext hook

#WebDevelopment #FrontendDevelopment #ProgrammingFundamentals #JavaScript #React #Hooks #ConceptExplanation #Tutorial #BestPractices #Intermediate #StateManagement

Magento 2 product types

There are six types of products in Magento:

• simple products

• grouped products

• bundle products

• configurable products

• virtual products

• downloadable Products

Simple products

Simple Product is the most frequently used product type by store owners. Every such Product is considered a single item that is not subject to customization.

For instance, a book. Every Simple Product is a physical item and has an SKU (Store Keeping Unit) number.

Every single product has a set of attributes that you can set up in the admin panel. A simple product is a standalone product that can be sold separately or as a part of grouped Product, Configurable Product, or bundle product.

Grouped products

Magento Grouped Product is a collection of Simple Products that can be bought together. For instance, someone buying a table may also be interested in complementary chairs.

You can create Grouped Products including a table and chairs and offer a discount. Your customer will be able to pay less when buying the set.

Products that are part of the grouped Product can be purchased together or separately. Take a look at the example grouped Product: Set of Sprite Yoga Straps:

As you can see, the Set of Sprite Yoga Straps grouped Product is a set of three simple products:

• Sprite Yoga Strap 6 foot

• Sprite Yoga Strap 8 foot

• Sprite Yoga Strap 10 foot

Bundle products

Bundle Product is a collection of similar products that differ in some detail. For instance, if a customer is looking for headphones, you can offer him five types of those that come from different manufacturers and are listed at different prices.

Your customer will surely appreciate that he's being presented with various options to choose from.

Another example is bundle product from default Magento 2 demo: Sprite yoga companion kit. When a customer goes to the product catalog and then to the Sprite yoga companion kit's product page, there is a "Customize and add to cart" button.

Then a customer can choose the type of ball and strap. Change the quantity of all simple products included in bundled product.

Grouped and bundle products in Magento 2 are beneficial types of products, and thanks to them, you can increase the sale of your products.

Configurable products

Magento Configurable Product is a product type that allows you to post products that offer additional options to consider before purchasing.

Configurable Products in Magento are collections of Simple Products. A Configurable Product isn't an actual item in your store and doesn't come on its own.

A Configurable Product is a kind of container for Simple Products, allowing the customer to modify them to their liking.

To generate product variations for a configurable product, Magento 2 creates simple products. Each variation is a simple product that is not visible in the product catalog individually.

An excellent example of a Configurable Product is a shirt, where you can select its size and color.

Thanks to Magento's Configurable Products mechanism, the customer can customize some of the Product's elements.

Downloadable Products

A downloadable product is a product that the customer can (surprise) download right after purchasing.

An e-book may serve as an example in this category. The customer expects that after he pays, he'll be able to download the Product to his hard drive.

An example of an excellent downloadable product is a Beginner's Yoga video from Magento 2 demo.

When customers buy a downloadable product, downloadable files will be visible on the "My downloadable products" page in a Customer account.

Virtual products

Magento Virtual Product is the one that can't be downloaded or shipped. Virtual Product is mostly additional service related to the particular Product.

For instance, when buying a PC, you can purchase an extra warranty extension - this is what a Virtual Product is.

On the other hand, a virtual product is simple without weight. When customers buy a virtual product and go to checkout - there is no shipping step.

Simple and virtual products are pretty similar, but it's clear that digital Product does not have weight.

Other product types in Magento 2

Up sells, related, and cross-sell products

Those listed above are products that are associated with other standalone products.

On the product page, you can see related and up-sell products. Related products are products similar to the main Product, and up-sell is identical as well, but they have higher prices.

Cross-sell products appear in the cart. For example, if you buy shoes, socks can be a cross-sell product.

Custom options

Product in Magento can have customizable options that allow offering a selection of options with a variety of text, selection, and date input types.

For example, you can sell licenses for your online course, and there can be three types of licenses. Basic, Standard, and Pro. Each one can have a different price.

Support for product types in Magento headless solutions

There are two main headless storefronts available for Magento 2: PWA Studio and Vue Storefront.

Let's look at how support for different Magento products looks in those headless storefronts.

Magento Luma is a benchmark for headless, and I hope that headless approaches will shortly support all Magento product types. Anyway, if you don't need support for virtual and downloadable products, VSF can be an option for you even now.

Conclusion

Magento 2 provides pretty extensive options when it comes to creating products. This will help you switch things up and diversify the product range offered at your Magento 2 online store to meet the customers' expectations. Headless solutions are behind Magento Monolith in terms of support for product types, but it's only a matter of time when full support will be in place.

#WebDevelopment #E-commerce #BackendDevelopment #FrontendDevelopment #PHP #Magento2 #PWAStudio #VueStorefront #Headless #ConceptExplanation #TerminologyDefinitions #Comparison #Intermediate #DigitalTransformation

What is React Router?

React itself is focused on building user interfaces, and it lacks a fully integrated routing solution. React Router is React's most popular routing library. It allows you to define paths in the same declarative style as most other libraries. A router allows your application to navigate by changing its browser's URL or browsing history while staying in synch with other elements.

Understanding routes

The matching logic to a component is delegated to the path-to-regexp library. With this behavior, you set which component should be displayed for a specific URL path.

It means that if you have, for example, an "about me" page and the path of this page is "/about-me," you need to assign a component that Reacts will render for that specific path.

What does React Router DOM do?

React Router DOM allows you to implement dynamic routing in web apps. React RouterDOM supports component-based routing according to the app's requirements and the framework. In contrast, the traditional routing architecture provides routing services in a configuration outside of a currently active app. React Router is the best solution for creating React Applications that run in the browser. React router DOM is the quickest way to create routing in React.

Let's dive in

This tutorial is split out among multiple areas. Our first task is to a create React app and install React Router using npm. Now we'll get down to some basic features of the React Router. Each concept and system for constructing these routes will be discussed along the course.

The full code for the project is published at this GitHub repository. This tutorial presents concepts of using React routing, the basics of React, hooks, and testing.

Prerequisites

I tested the code in Node 14.17.3. I set up the project using Create React App. You will also need a basic knowledge of JavaScript, HTML & CSS add React to understand what is going on here, but if you need to learn React Router, you are familiar with those things.

By The Way: HTML means HyperText Markup Language, so it's not a https://time.com/12410/11-of-americans-think-html-is-an-std/.

Scaffold the project

As I mentioned before, you'll require the Node installed on your computer for this tutorial. Then you can follow https://create-react-app.dev/docs/getting-started/ to set up React project using Create React App.

Changes after this: step: https://github.com/Frodigo/react-router-tutorial/commit/dd4e2230153228220a0ed75136c74dc556aad657

Setting up React Router

Now you can install React Router by using npm or yarn. Let's use npm

npm install react-router-dom@6

Changes after this: step: https://github.com/Frodigo/react-router-tutorial/commit/89ac1a9a16ec0fac0c1317635b72cf4f7cd72dcf

Cleanin' Out My Closet

Before we go deeper, let's clean some code that CRA generated for us.

Replace index.js with this content:

import React from "react";
import ReactDOM from "react-dom";
import App from "./App";

ReactDOM.render(<App />, document.getElementById("root"));

Remove these files: reportWebVitals.js, index.css, logo.svg, App.css, and App.test.js -who needs tests??? But wait, we can add our own tests later, don't worry, I am just trolling you.

Replace App.js with this content:

import React from "react";

export const App = () => {
  return (
    <>
      <h1>Hello, hello, hello</h1>
    </>
  );
};

export default App;

Change title and description in public/index.html and remove unnecessary comments. The final result should look like this:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <meta name="theme-color" content="#000000" />
    <meta name="description" content="React router tutorial" />
    <link rel="apple-touch-icon" href="%PUBLIC_URL%/logo192.png" />

    <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
    <title>React Router example</title>
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div id="root"></div>
  </body>
</html>

Changes after this: step: https://github.com/Frodigo/react-router-tutorial/commit/82839415d55ad15c2411fec640a57a6c0bb8bcd7

It's not time for styling

Yeah, so let's use React Bootstrap, which provides some components and styles to focus on writing React code. It is a good move, isn't it?

npm install react-bootstrap bootstrap@5.1.3

Import bootstrap styles in the index.js. Just add this line after other imports:

import "bootstrap/dist/css/bootstrap.min.css";

OK, that all was easy. Let do something less trivial than importing things from npm.

Changes after this: step: https://github.com/Frodigo/react-router-tutorial/commit/96843a7dd88cb1175790e527b86e5a25cc4e0fb0

Add Router component

To get React Router working in your App, you need to add a Router. Basically, it means that you need to wrap your app with a top-level router that makes all other React Router components and hooks work. A router is stateful, and it creates history with the initial location and subscribes to the URL.

React Router can subscribe to the URL changes thanks to the History object. Each user action that changes URL is kept in History Stack.

There are three types of those actions: PUSH, POP, and REPLACE.

• PUSH - a new entry is added to the history stack

• POP - it happens when a user click Browser's back or forward buttons

• REPLACE - Replace action is similar to PUSH, but it replaces the current entry in the history stack instead of adding a new one

A location is an object built on top of a window. location object. In this object, you can find information about URL, and in general, it represents where a user is at the time.

There are three types of Routers in react-router-dom:

• BrowserRouter - recommended for running React Router in a Web browser

• HashRouter - is used for apps where the URL should not be sent to a server for some reason. It's not recommended to use the Hash router unless you absolutely have to.

• MemoryRouter - the common case of using MemoryRouter is testing. It stores all information in an array.

OK, so let's wrap our app by BrowserRouter.

index.js:

import React from "react";
import ReactDOM from "react-dom";
import { BrowserRouter } from "react-router-dom";
import App from "./App";
import "bootstrap/dist/css/bootstrap.min.css";

ReactDOM.render(
  <BrowserRouter>
    <App />
  </BrowserRouter>,
  document.getElementById("root"),
);

Changes after this: step: https://github.com/Frodigo/react-router-tutorial/commit/cdd0fbca793766e8b85ae01ed4ead1d795de1a68

Add Navigation and links

Update app component (App.js) file with this content:

import React from "react";
import { NavLink } from "react-router-dom";
import { Navbar, Container, Nav } from "react-bootstrap";

export const App = () => {
  return (
    <>
      <Navbar bg="light" expand="lg">
        <Container>
          <Navbar.Brand>
            <NavLink
              to="/"
              style={{ textDecoration: "none", color: "inherit" }}
            >
              Your account
            </NavLink>
          </Navbar.Brand>
          <Navbar.Toggle aria-controls="basic-navbar-nav" />
          <Navbar.Collapse id="basic-navbar-nav">
            <Nav className="me-auto">
              <NavLink to="/address" className="nav-link">
                Address book
              </NavLink>
              <NavLink to="/orders" className="nav-link">
                Orders
              </NavLink>
            </Nav>
          </Navbar.Collapse>
        </Container>
      </Navbar>
      <Container className="mt-3">
        <h1>Hello, hello, hello</h1>
      </Container>
    </>
  );
};

export default App;

We imported a NavLink component here from react-router-dom:

import { NavLink } from "react-router-dom";

A NavLink component is a special type of the Link component with an additional feature. It can have an "active" class where the URL is the same as "to property.

A Link React component renders <a> tag with real href property. The difference about the real <a> tag is that React Router will handle navigation to specific locations when you use Link (and NavLink).

So in our app, even we haven't declared any routes yet, the URL is changed without page reloading thanks to React Router.

Besides, we imported there some Bootstrap stuff:

import { Navbar, Container, Nav } from "react-bootstrap";

Summarizing, we added three links: HomePage: /, Address book: /address, and Orders: /orders.

Changes after this: step: https://github.com/Frodigo/react-router-tutorial/commit/0492a826f8047a48161ccb87e535b9edc280cea6

Add the first route

React Router is a declarative routing framework that means you configure Routes to use standard React components.

At the end of this step, you now have a react application to find navigation links showing the components for each route.

Let's implement the first route. To do so, we need just to import Route and Routes components in the app and use them in this way:

import { Routes, BrowserRouter, Route} from "react-router-dom";

(...)

<BrowserRouter>
    <Routes>
        <Route path="/" element={<App />} />
    </Routes>
</BrowserRouter>

So we have a route that handles the "/" path and renders the App, a React component. Basically, nothing has changed in our app so far. Let's implement other routes.

Changes after this step: https://github.com/Frodigo/react-router-tutorial/commit/3157af6cfe8db2f5354a0fbde9029b1073658844

Add first nested routes and outlet

React Router uses nested routes to provide the most detailed routing details inside child components. Those routes group your routing information directly into components to render other components.

By the finish of this step, you will have various ways of providing info. This is a little additional code, but the routes keep the child's parents in line. Not every project uses a nested route: some prefer an explicit list.

Nested routes allow you to build a complex system of routing. Each route defines a portion of the URL through segments, and a single URL can match multiple routes. Take a look:

Here is our main route:

/

Here is the route for the address book:

/address

And here is the route for address details

/address/:addressId

So the route is built by three routes: / + address/ + :/addressId

Let's implement that scenario. Please, replace **<Route path="/" element={<App />} />** by:

<Route path="/" element={<App />}>
  <Route path="address" element={<AddressBook />}>
    <Route path=":addressId" element={<AddressDetails />} />
  </Route>
</Route>

Hero you go!

Of course, we need to define two new components: AddressBook, and AddressDetails

src/routes/AddressBook/addressBook.js:

import React from "react";

export const addressBook = () => {
  return <p>Address book will be here</p>;
};

export default addressBook;

src/routes/AddressBook/index.js

export { default } from "./addressBook";

Do the same for address details (and do not forget about importing these routes in index.js!)

That should work, but wait. If you go now for the address page, you will see that the address route is rendered, but it looks pretty the same as the index route, but we except that there will be a paragraph: Address book will be here.

To render the content of any child, you need to use the Outlet component that renders the next match in a set of matches.

Please import the Outlet React component to the App component:

import { NavLink, Outlet } from "react-router-dom";

and add it below the <h1>

<Container className="mt-3">
  <h1>Hello, hello, hello</h1>
  <Outlet />
</Container>

Now the paragraph from the address book component is in place.

Changes after this: step: https://github.com/Frodigo/react-router-tutorial/commit/4fcee983b94da41991244463b6092fbfd80255ad

Add Index routes

Let's go ahead and add some content to the address book. First, add some addresses:

const addresses = [
  {
    id: 1,
    addressName: "Polna 1, Wrocław",
  },
  {
    id: 2,
    addressName: "Wrocławska 2, Warszawa",
  },
];

Then, render navigation with addresses:

const navLinks = addresses.map((address) => {
  return (
    <ListGroupItem key={address.id}>
      <NavLink to={`/address/${address.id}`} key={address.id}>
        {address.addressName}
      </NavLink>
    </ListGroupItem>
  );
});

const shouldDisplayNav =
  navLinks && navLinks.length ? (
    <ListGroup>{navLinks}</ListGroup>
  ) : (
    <p>There are no addresses.</p>
  );

Return all stuff with a nice layout:

return addresses ? (
  <Row>
    <Col sm="3">{shouldDisplayNav}</Col>
    <Col sm="9">
      <Outlet />
    </Col>
  </Row>
) : (
  <Row>
    <p>There are no addresses.</p>
  </Row>
);

Do not forget about imports:

import { NavLink, Outlet } from "react-router-dom";
import { ListGroupItem, ListGroup, Col, Row } from "react-bootstrap";

On the right of navigation, there is a space for address details, but initially then is empty space. When you click on an address in navigation, you can see address details.

There is a way to add some improvements! Let's add a paragraph that says: "Please select an address." To do so that you can use another pretty cool feature of React Router called: Index route

Add this code to index.js to AddressBook route component:

<Route index element={<p>Select an address.</p>} />

Now, when you go to the address book, you can see "Select an address" text by default.

Let's do something similar for the home route:

<Route
  index
  element={
    <>
      <h2>Welcome in your account.</h2>
      <p>Please use the navigation above to see Address book or your orders.</p>
    </>
  }
/>

Remove this code from App.js

<h1>Hello, hello, hello</h1>

Changes after this: step: https://github.com/Frodigo/react-router-tutorial/commit/cb81a97541fb8de9601f8774cfb267967ea6cd38

Use URL params

We have already defined a route for Address Details that receives addressId param:

<Route path=":addressId" element={<AddressDetails />} />

When you click on addresses, the URL is changing:

http://localhost:3000/address/1
http://localhost:3000/address/2

"1" and "2" in this case are addresses ID. The question is: how do we handle those params in the AddressDetails React component?

useParams hook

React Router provides a useParams hook that allows you to handle URL params. Take a look:

import React from "react";
import { useParams } from "react-router-dom";

export const AddressDetails = () => {
  const { addressId } = useParams();
  return <p>Address details for {addressId} will be here</p>;
};

export default AddressDetails;

Now, addressId is handled by the AddressDetails component.

Changes after this step: https://github.com/Frodigo/react-router-tutorial/commit/f2f833a41e994bd1dac366648d44739d98a38a82

Use search params

React Routes provides a useSearchParams hook that allows you to read and modify a query part of a URL (q=). Let's use it to add some filtering to the App.

First import useSearchParams hook in the AddressBook React component ad get searchParams, and setSearchParams from it:

import { useSearchParams } from "react-router-dom";

// below in the compoonent body:

const [searchParams, setSearchParams] = useSearchParams();

Second, add a search form. To do so, add this code at the beginning of the return function:

<Col sm="12">
  <nav>
    <InputGroup size="sm" className="mb-3">
      <InputGroup.Text id="address-search">
        Search for an address
      </InputGroup.Text>
      <FormControl
        aria-label="Search for an address"
        aria-describedby="address-search"
        value={searchParams.get("filter") || ""}
        onChange={(event) => {
          const filter = event.target.value;
          if (filter) {
            setSearchParams({ filter });
          } else {
            setSearchParams({});
          }
        }}
      />
    </InputGroup>
  </nav>
</Col>

A function bound on the onCahnge event sets the current input value to the URL query param.

Third, let's read the query param and filter addresses by it:

const navLinks = addresses
  .filter((address) => {
    const filter = searchParams.get("filter");
    if (!filter) return true;

    let name = address.addressName.toLowerCase();

    return name.startsWith(filter.toLowerCase());
  })
  .map((address) => {
    return (
      <ListGroupItem key={address.id}>
        <NavLink to={`/address/${address.id}`} key={address.id}>
          {address.addressName}
        </NavLink>
      </ListGroupItem>
    );
  });

In the previous step, we named a param by word: filter, and now we can read that value by using this: searchParams.get('filter');

Changes after this step: https://github.com/Frodigo/react-router-tutorial/commit/50954adea6242fbc4d3ebaef05979050206134cd

Handle no matching route

The last thing I want to show you is the no-match route. It's a case when the user goes to a route that does not exist, for example,/blablabla

To handle that, add this route component definition at the end of your route components definitions:

<Route
  path="*"
  element={
    <main>
      <p style={{ padding: "30px", textAlign: "center" }}>
        There's nothing here!
      </p>
    </main>
  }
/>

That code handles all routers not handled by other defined routes components. On the other hand, if no routes match, those elements will be rendered. Of course, you can use the react component as well.

Changes after this step: https://github.com/Frodigo/react-router-tutorial/commit/0f3e6588b1bc5cb6e6f6e298a527a8d856247e2b

An additional thing: protected Routes

A protected route is used to ensure only logged-in users can use some places on your site. Typically we create e a secure route component for someone in the system to use /admin when they attempt to connect. However, some aspects of React Router must first be covered.

Basically, you can create a special React component that will check if a user can go to a protected route or not.

Working Demo

Here you can see the demo of the application we developed with react-router:

https://react-router-tutorial-omega.vercel.app/

Source code

Here you can find the source code for this tutorial: https://github.com/Frodigo/react-router-tutorial

Here are the commits for each step:

1. https://github.com/Frodigo/react-router-tutorial/commit/dd4e2230153228220a0ed75136c74dc556aad657

2. https://github.com/Frodigo/react-router-tutorial/commit/89ac1a9a16ec0fac0c1317635b72cf4f7cd72dcf

3. https://github.com/Frodigo/react-router-tutorial/commit/82839415d55ad15c2411fec640a57a6c0bb8bcd7

4. https://github.com/Frodigo/react-router-tutorial/commit/96843a7dd88cb1175790e527b86e5a25cc4e0fb0

5. https://github.com/Frodigo/react-router-tutorial/commit/cdd0fbca793766e8b85ae01ed4ead1d795de1a68

6. https://github.com/Frodigo/react-router-tutorial/commit/0492a826f8047a48161ccb87e535b9edc280cea6

7. https://github.com/Frodigo/react-router-tutorial/commit/3157af6cfe8db2f5354a0fbde9029b1073658844

8. https://github.com/Frodigo/react-router-tutorial/commit/4fcee983b94da41991244463b6092fbfd80255ad

9. https://github.com/Frodigo/react-router-tutorial/commit/cb81a97541fb8de9601f8774cfb267967ea6cd38

10. https://github.com/Frodigo/react-router-tutorial/commit/f2f833a41e994bd1dac366648d44739d98a38a82

11. https://github.com/Frodigo/react-router-tutorial/commit/50954adea6242fbc4d3ebaef05979050206134cd

12. https://github.com/Frodigo/react-router-tutorial/commit/0f3e6588b1bc5cb6e6f6e298a527a8d856247e2b

Summary

React Router lets you handle all the routes in a React application. You can use it for a web app or even for React native app.

The router is one of the main React Router components, and for web apps, there is a BrowserRouter react component, a router implementation that uses HTML5 History API.

React Router provides other essential components are Routes, Route, Link, and NavLink.

Besides, there are a few hooks like useParams, useSearchParams, and useNavigate.

So react-router package provides just components and just hooks, and those all together allow you to create complex routing systems easily.

#WebDevelopment #FrontendDevelopment #JavaScript #HTML #React #ReactRouter #Bootstrap #GitHub #Tutorial #DeepDive #ProjectSetup #Intermediate #APISecurity #Performance

I want to invite you to the journey throughout react-redux. You will see:

• What choice of approach to state management in react apps is important?

• What is redux, and why should you use it or not?

• What are Flux architecture and event sourcing?

• What is the architecture of the typical redux app?

• How to manage side effects in the redux app?

• What are alternatives for redux-thunk middleware?

• What hooks react-redux offer?

• What is the best approach for testing redux apps?

What is state management?

State management is designed to enable the exchange and use of data between different sectors. It creates a concrete data structure that represents the state of your app for you to read.

Most frameworks, including React, have a way for components to control the state. It's also helpful for applications with few components, but state management across components can quickly become a task.

That is why you need state management tools to make it easier to maintain the state. It is clear that state management becomes difficult as the app is complicated, so you require a state-management tool like Redux.

Redux is a predictable state container for JavaScript apps and offers a centralized way to manage the state. Using a framework like React, we can tell certain parts of code only to show specific values of the state.

State property updates will be automatically uploaded to the front end (if rendered there). In all, state references a condition of something at a given moment, such as whether a modal is opened or not, which data should be visible, which view is active, and so on.

Why use redux?

Redux is a pattern and library for managing and updating application states using events called actions that accomplish this task by defining actions that are dispatched to reducers. All actions in an app can have a type and a payload.

Reducer accepts action and changes state depending on recipient Action Type and Payload. Reducers are pure functions and therefore are predictable.

A simple function returns the same output for the same data. In addition to communication with our application, we can subscribe to data updates. It is a simple yet elegant solution to facilitate state management for small and large applications.

When to use Redux

The Redux API allows you to maintain your Apps state and keep it more predictable. The idea of adding code can seem like a bit of a chore and make complicated things look a little bit overwhelming, but that can depend on the decision-making from the architecture. If you're still unsure of who needs them, you do not. The usual scenario starts when your company's application expands to the level where maintaining the app state becomes a hassle. You are seeking to make managing the user's app straightforward. These benefits come with tradeoffs and constraints, but all of these tradeoffs come with limitations and tradeoffs, including the addition of boilerplate code.

Why do I need to use React-Redux?

React Redux is the official Redux Interface Library for React. If you use Redux with any UI framework, you will generally use a library with its own internal "binding" library to put Redux together with a UI framework. Redux is a standalone library used with any UI layer or framework, including React Angular Vue Ember and Vanilla JS.

Redux architecture

Let's look at the react redux architecture and what you can find in a typical redux app.

Flux

React redux implements the Flux architecture (proposed by Facebook). The base rule of that architecture is that data flows in a single direction, and also redux state can be changed only in one place.

The other concept of Flux is that writing data is separated from reading data. It's based on the Command Query Responsibility Segregation (CQRS) design pattern.

That separation is good because typically, in apps, reading data is more frequent than writing, so it's good to separate them and scale, develop and maintain separately. Of course, sometimes using CQRS does not make sense, but it depends on projects requirements (as always)

In the Flux architecture, there are three main areas:

• view - that what you see and place where you can dispatch actions that can change data in a store

• dispatcher - receives actions and pass them to stores

• store - stores information

So Redux implements flux architecture in its way, and keep in mind that other tools also implement Flux but in a slightly different way. Take a look at https://mobx.js.org/README.html, for example.

Event sourcing & time traveling

Another idea (pattern, architecture) that react redux implements is event sourcing. That pattern is more known on the backend side. Event sourcing on the frontend in redux apps means that the state reading by the view is not the source of data.

The redux state and data are created by events (actions in react redux architecture – more information below). Typically you have a default store state, and you change that state by dispatching actions.

Thanks to that, you can build a state of what you want by triggering particular actions. Let's imagine a tester finding a bug in an app and reproducing that bug in your local environment. You can need to reproduce actions history.

Moreover, you can travel back and forth in time by performing and withdrawing specific actions and seeing the unique state for each action.

Redux has a global store and brings your component's states to one central area. The prominent place where we store the state is called a store.

That also provides an additional way for examining how a particular period an app's state changes. The store is immutable, which means it can't be directly modified. It can be cloned and replaced in place with updated properties. This cloning gives us a view of our app useful for debugging purposes, particularly in the Context of a specific app's state change.

Redux Reducers

A reducer is only a pure function that takes two arguments and returns the current state in your app.

The first argument is the current state, and the second is an action that will modify that state. The Reducer function returns a new state based on provided current state and action.

Take a look at the example reducer:

export function CarsReducer(state, action) {
  switch (action.type) {
    case "ADD_CAR": {
      return {
        messages: [...state.cars, action.car],
      };
    }

    case "REMOVE_CAR": {
      const indexToToRemove = state.cars.indexOf(action.car);

      if (indexToToRemove >= 0) {
        return {
          cars: [...state.cars.splice(indexToToRemove, indexToToRemove)],
        };
      }

      return state;
    }

    default: {
      return state;
    }
  }
}

Thar CarsReducer can handle two actions: ADD_CAR and REMOVE_CAR. Let's take a look at what actions are in Redux.

Redux Actions

Actions in redux are JavaScript objects containing two features called type and payload. These actions will be used as arguments through the API method that calls Redux dispatch when an item needs dispatch. To "call" this action, we have to use a reducer in our store to update our state. We then use this function to create a new store state to preview how the app looks after actions are sent on.

Take a look at the example action creator:

const addCar = (car) => {
  return {
    type: "ADD_CAR",
    car,
  };
};

Another convention is to send a car object as a field of the payload:

const addCar = (car) => {
  return {
    type: "ADD_CAR",
    payload: {
      car,
    },
  };
};

Both versions are good. They are only conventions. I prefer the first one.

Those functions are called action creators because they return a plain JavaScript object (action object) that you can dispatch to the store.

Redux & performance

In terms of performance in React, re-renders are something that impacts performance the most. When you use the React way to handle state, for example, hooks or even class components with private state, re render is necessary when the state is changed.

When you are integrating redux with react, the state is keeping outside react. That means the react' components read data from the redux store, and in some cases, re-renders can be unnecessary. This Is like magic, but redux can you prevent redundant re-renders OOTB.

Comparing redux performance with React Contexts, there is a vast difference. When you have a significant Context with big data objects, and there is a change in this Context, all Context's subscribers (basically children) will be re-rendered.

Of course, you can reduce redundant re-renders by using the useCallback or useMemo hooks, but you need to take care of it by yourself and write additional code.

When you use Redux and dispatch some action using the useDispatch hook, only components that read data changed data will re render.

That makes a difference. Of course, this does not mean that React contexts are wrong, and redux is excellent. You can manage the state efficiently both ways, and the performance typically depends on implementation (and quality).

That means the redux can help you with performance, and you should consider this when you design state management in your app.

Collaborative UI

Another thing in terms of performance is apps that work in real-time. For example, Google docs. There you can edit documents with other users in real-time. In a case like that, Redux's architecture based on events is better because it's easier to send only events between users than sending all document data and handling change.

So using redux or not depends on the project type.

You may also ask if Redux can have a destructive impact on the performance of a react app? Sometimes - yes, but it's typically because not of redux, but because of the wrong design of an application.

React redux state is outside React, so when you design and develop a redux app, you need to decide which data should be a part of the redux store and a private state of components. Good design of state management can help to avoid performance issues.

Side effects

Some actions can have side effects. For example, when you add the product to a cart, you need to display a notification. On the other hand, you can also need to work with async data. I mean, send a request for data before redux action or after.

You can manage side effects in a react component, but this is not a good idea because user action, or generally speaking an operation, is divided into two parts

1. pure - redux action - handled by reducer

2. impure - side effect - controlled by a react component

A better solution is adding one common type of place in a react app when you can handle operations. That place is called: redux middleware.

Redux middleware

Redux middleware is a building block that allows you to encapsulate sending redux actions and manage side effects, async data in one place.

There are three types of redux middleware:

1. Thunks (https://github.com/reduxjs/redux-thunk)

2. Sagas (https://redux-saga.js.org/)

3. Observables (https://redux-observable.js.org/)

If you are developing redux apps, you should choose one of the middleware, and then Redux and middleware are responsible for the state management, and components don't need to handle side effects. Hence, they are more readable and more superficial because they only display data.

Let's go dive into each redux middleware type.

Redux Thunk

Redux-thunks are the simplest to understand, so let's start from them! Thunks is a function that can dispatch any redux action directly to a redux store.

Moreover, you can dispatch many actions in one thunk and add additional logic of dispatching so that you can dispatch action conditionally or in a loop. Also, a thunk can call other thunks, so whatever you need, all of this is in one place.

The significant advantage of thunks is that components don't know anything about the thunk that it calls. All dependencies and logic are inside thunks, and components are only called thunk. All magic is inside.

Take a look at the example thunk:

// redux action
function setUser(userData) {
  return {
    type: "SET_USER",
    userData,
  };
}

// redux action
function setError(errorMessage) {
  return {
    type: "SET_ERROR",
    errorMessage,
  };
}

// The thunk
function fetchUserData(userId) {
  return function (dispatch) {
    return fetch(`https://my-api.com/user/${userId}`).then(
      (data) => dispatch(setUser(data)),
      (error) => dispatch(setError(`Something went wrong... ${error}`)),
    );
  };
}

You can see two redux actions in the code above: setUser, setError, and the thunk named fetchUserData. That thunk receives userId as a parameter and calls https://marcin-kwiatkowski.com/blog/graphql/2-ways-of-handling-graphql-errors-in-apollo-client using fetch and then dispatch setUser action, or setError hook if the API returns error.

Take a look at another example with more logic:

function fetchUserB2Bdata() {
  return function (dispatch, getState) {
    const user = getState().user;

    if (!user) {
      return dispatch(setError("User is not authenticated."));
    }

    if (!user.isB2Buser) {
      return dispatch(setError("User is not a B2B user."));
    }

    return fetch(`https://my-api.com/user/b2b/${user.id}`).then(
      (data) => dispatch(setUserB2Bdata(data)),
      (error) => dispatch(setError(`Something went wrong... ${error}`)),
    );
  };
}

As you can see, there is a getState function that allows you to get the current state and do what you need depending on it.

Those examples are elementary, and I wanted to show you (what I am writing about for a while ) the advantages of using thunks: handle async data, encapsulate actions with side effects, and async data.

Sagas (redux-saga)

Let's take a look at the second type of redux middleware. On the homepage of redux-saga, you can read that it's "An intuitive Redux side effect manager." Let's check it's the truth! :)

Here is the example piece of code that uses redux-saga:

import { call, put, takeEvery } from "redux-saga/effects";
import Api from "...";

// Worker saga will be fired on REQUEST_USER actions
function* fetchUserData(action) {
  try {
    const userData = yield call(Api.fetchUser, action.payload.userId);
    yield put({ type: "SET_USER", userData });
  } catch (error) {
    yield put({ type: "SET_ERROR", errorMessage: error });
  }
}

// Starts fetchUser on each dispatched REQUEST_USER action
function* mySaga() {
  yield takeEvery("REQUEST_USER", fetchUserData);
}

It is intuitive, isn't it?

I hope you will agree with me that at first glance, it looks more complicated than redux-thunk. Let's explain it a little bit.

The concept of redux-saga is similar to the saga design pattern. Each saga is an independent logic that is fired when some specific actions are dispatched.

In the example above, there is a fetchUserData saga that is fired on every REQEST_USER redux action.

The takeEvery function is a redux-saga effect. There is also the takeLatest effect which is fired on the latest specified redux action.

There are more effects, so you need time to understand redux-saga API. Moreover, redux-saga uses JavaScript generators that ate powerfully but also required more attention to understand them.

Epics (redux-observable)

The last type of redux middleware which you should consider when you design a redux app is redux-observable. It's based on https://github.com/ReactiveX/RxJS.

In this case, redux-actions are implemented as RxJS streams, so you have a stream of actions and a stream of state. Using redux-observable, you can create Epics that describes connections between actions. You can think about epics like sagas from redux-saga.

For now, I don't want to go deeper with epics (and sagas as well), but you can expect separate articles about them in the future.

Summarizing – sagas and epics have a significant entry threshold, so you and your team should think twice before you decide to use them. It does not mean that they are wrong. Everything depends on a project's requirements and team credentials.

However, I will not lie if I say that redux-thunk is a good choice in 90% of cases.

Modern redux with hooks

The React world can be divided into two eras: before Hooks were introduced and after Hooks were introduced.

Before, there was a connect function provided by the react redux, and you were able to map state and dispatch to props of components. Also, a connected component could give props from a parent component, so you needed to merge props from components and redux.

Writing with this method added even more redux boilerplate to your code to add child component that has access to the redux store to the component tree.

Luckily we now have hooks, and things look more straightforward.

Hooks

React's new "hooks" API gives functions the ability to use local component states, execute side effects, and so on. React also lets us write custom hooks enabling us to extract reusable hooks to add our behavior for React's built-in hooks. React-Redux has its standard hook APIs that allow React components to subscribe to Redux stores, read state, and dispatch actions.

useSelector

The useSelector hook allows you to read a state from the redux store. Each call to useSelector() creates an individual subscription to the Redux store.

Take a look at the example of a react component that uses of the useSelector:

import React from "react";
import { useSelector } from "react-redux";

export const UserDetails = () => {
  const user = useSelector((state) => state.user);
  return <h1>Hello, {user.name}</h1>;
};

useDispatch

The useDispatch hook returns a reference to the dispatch function from the Redux store. Thanks to that, you can dispatch actions in a react component as needed.

import React from "react";
import { useDispatch } from "react-redux";

export const LogOut = ({ value }) => {
  const dispatch = useDispatch();

  return <button onClick={() => dispatch({ type: "LOG_OUT" })}>Log out</button>;
};

As you can see, using Redux with hooks is pretty simple, and keep in mind that it's recommended approach (instead of using connect function).

Redux code boilerplate

Now let's focus on something which is a considerable disadvantage of redux - code boilerplate. When you create a new app, you set up redux and are ready to go... you need to write a lot of code: reducers, action creators. It's instead not enjoyable, more frustrating, but there is a solution for that!

Redux toolkit

Redux toolkit is an Opinionated set of tools that can help create redux code and focus on the core logic your app needs. Thanks to that toolkit, you can write less code and do more work at the same time. Redux toolkit can help with store setup, creating reducers, immutable update logic, and more.

Take a look at the examples here: https://redux-toolkit.js.org/tutorials/quick-start.

Redux DevTools

Redux DevTools is a browser extension that allows you to see the status of your Redux store at any given time. It is how we can time travel by our app - as different changes take place.

If the app starts to send more actions, the software will check the user's interaction on all of its features using Redux DevTools. This is useful for debugging as your app grows, so having a running log of how your redux store state is updated will give you valuable insight into how your app ends up looking how it does.

What I like the most is inspecting actions, the current state at the moment, and time traveling. It's highly recommended to use https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en to debug redux apps.

Testing redux

Redux is simply a library that ensures we follow a particular pattern for updating our global state. Should we unit test stores, reducers, actions, and so on?

In my opinion, we shouldn't. Redux is an implementation detail, and it should be hidden in tests even when I think about redux middleware. From the perspective of a test, you don't have to use thunks, sagas, or epics. What is vital is that the state should be changed.

So I recommend testing the redux more integrally than the unit.

For example, instead of testing actions and reducers, test component that reads data and triggers actions. Test it from the user's perspective and assert that results are that as they should be.

React Redux Tutorial for Beginners: The Complete Guide

The most simplified Redux tutorial I want when I'm figuring it out. Includes the Redux Toolbox and Redux hooks! There are many redux tutorials, but many of them are outdated, so I plan to write a new one that is up to date with approaches and techniques that we have already known in 2021. Stay tuned!

Conclusion

In the end, I want to say that Redux is a complex way to manage the state in react apps and still is an option in 2021 for the state management engine for React Apps. Hooks provided by the library are effortless to use and powerful. Thanks to the redux toolkit, there is also a way to avoid a large amount of redux boilerplate code.

In some cases, Redux is a good choice, and also even if you choose Redux, you need to select other things: which middleware should I use?

Redux-thunk, redux-saga, or redux-observable?

Those middlewares can help manage side effects and asynchronous logic in different ways. Also, the level of complexity of those is different (thunks are most straightforward).

Do I need redux?

Is another question about architecture? Do you need redux and event sourcing? Maybe alternatives as https://mobx.js.org/README.html, https://react-query.tanstack.com/ or https://swr.vercel.app/ will be better for `you?

Moreover, Facebook is actively working on something new for state management in react apps. Check out https://recoiljs.org/.

Do I migrate from redux?

The final question is, when I have the redux app, should I migrate to something else?

I was fascinated with how the redux became popular a few years ago, and I'm just as fascinated with how suddenly its popularity has declined.

When you think about migrating from redux, you need to have good reasons. Migrating because the community declines it is not a reason.

If, after a few years, it turned out that the choice of redux was not the best, it only emphasizes the importance of design and choosing the exemplary architecture for a specific project.

So, if you have reasons and money, please migrate from redux, but migrate if you want to migrate. Please give it up.

#WebDevelopment #Frontend #React #StateManagement #JavaScript #Redux #ReduxThunk #ReduxSaga #ReduxObservable #ConceptExplanation #DeepDive #BestPractices #Intermediate #Performance #Architecture

JSX is an XML/HTML-like syntax from React that extends ECMAScript. JSX allows you to write HTML code mixed with JavaScript. Take a look at the following example:

export const App = () => {
  return (
    <main id="root">
      <h1>Hello Folks!</h1>
      <p>
        Random question: Is <strong>FC Barcelona</strong> win any match in the
        Champions League this season?
      </p>
    </main>
  );
};

export default App;

Each JSX code is converted into the React.createElement function, which the web browser knows. Take a look at the converted code I showed you in a previous snippet:

export const App = () => {
  return React.createElement(
    "main",
    { id: "root" },
    React.createElement("h1", null, "Hello Folks!"),
    React.createElement(
      "p",
      null,
      "Random question: Is ",
      React.createElement("strong", null, "FC Barcelona"),
      " win any match in the Champions League this season?",
    ),
  );
};

export default App;

The react createElement function creates and returns a new React element. Here is the function signature:

React.createElement(type, [props], [...children]);

The type argument can be an HTML element or React element (or even React fragment). The second argument is the props object which contains HTML tag attributes or props of a React element. The last argument is children, and so this is another jsx element transformed to React createElement function.

In the above code, you can see there are nested elements. All jsx tags are transported to react createElement functions, and regular javaScript can understand them.

So if you ask what is jsx in React, what is jsx meaning, I may answer you that is a special syntax that allows mixing plain JavaScript and HTML elements to speed up development. Then you can ask...

Is JSX necessary for React?

It's not so if you don't like JSX syntax, or you want to write JavaScript code without configuring babel to transpioling JSX syntax to actual javascript code, you can write React apps without JSX.

Pro-tip for you then: if you want to avoid writing React.createElement too much, you can try something like this:

const e = React.createElement;

ReactDOM.render(
  e('div', null, 'Are you sure you don't want to use JSX?'),
  document.getElementById('root')
);

React JSX Explained with Examples

React JSX is React's core concept. If you have a good understanding of it properly, then you can write React code efficiently. Let's see common use cases of JSX in React.

How do I add JavaScript code in JSX?

To add JSX-style code, you need to use curly brackets like this:

export const App = () => {
  const welcomeMessage = "Hello folks!";

  return (
    <main id="root">
      <h1>{welcomeMessage}</h1>
    </main>
  );
};

export default App;

JSX doesn't allow to render objects directly as a JSX tag, so this react code is not valid, and the error occurs when using JSX Expression when rendering an object.

export const App = () => {
  const welcomeMessage = {
    text: "Hello folks!",
  };

  return (
    <main id="root">
      <h1>{welcomeMessage}</h1>
    </main>
  );
};

export default App;

But you can write arrays in JSX Expressions because arrays are converted to strings while rendering. So this react' component is valid:

export const App = () => {
  const welcomeMessage = ["Hello", " ", "folks", "!"];

  return (
    <main id="root">
      <h1>{welcomeMessage}</h1>
    </main>
  );
};

export default App;

Attributes

JSX allows you to use native HTML attributes and your own custom attributes as well. For native HTML attributes, JSX uses camel case convention instead of the normal HTML naming convention. Besides, please note that, for example, a class word is a reserved keyword and for either. For those keywords, JSX uses a className for a class and a htmlFor for a reserved keyword (for).

Custom HTML attributes in JSX

For custom HTML attributes, you must use a data prefix. It looks pretty the same as regular HTML.

export const App = () => {
  const welcomeMessage = ["Hello", " ", "folks", "!"];
  const isCustom = true;

  return (
    <main id="root">
      <h1 data-isCustom={isCustom}>{welcomeMessage}</h1>
    </main>
  );
};

export default App;

As you can see in that react component on <h1> HTML tag, I used the data-isCustom attribute and curly braces to pass value to the attribute. Moreover, you can pass values to attributes of HTML tags using string literals like this:

export const App = () => {
  const welcomeMessage = ["Hello", " ", "folks", "!"];

  return (
    <main id="root">
      <h1 data-mode="default">{welcomeMessage}</h1>
    </main>
  );
};

export default App;

JavaScript Expressions

JavaScript expression may be used inside JSX. What is not surprising, I suppose, when you want to use a JavaScript expression, you need to wrap it by curly braces {}

If statements

You cannot use if-else statements in JSX. Instead, you can use conditional or JavaScript ternary expressions. Take a look at the simple React component with JSX if statement:

export const App = () => {
  const welcomeMessage = ["Hello", " ", "folks", "!"];
  const shouldDisplay = true;

  return (
    <main id="root">
      {shouldDisplay && <h1 data-mode="default">{welcomeMessage}</h1>}
    </main>
  );
};

export default App;

For if/else you can use something like this:

{
  shouldDisplay ? <h1 data-mode="default">{welcomeMessage}</h1> : "no way!";
}

I prefer to explode JavaScript expressions to const (and sometimes memorize them using React useMemo hook because of performance reasons). Take a look at the JSX code below:

export const App = (props) => {
  const { hasError } = props;
  const welcomeMessage = "Hello folks!";
  const errorMessage = "Something went wrong.";

  const shouldDisplayError = hasError ? (
    <p>{errorMessage}</p>
  ) : (
    <h1>{welcomeMessage}</h1>
  );

  return <main id="root">{shouldDisplayError}</main>;
};

export default App;

Looping

When you want to render a JavaScript array using JSX, you can use something like this:

export const App = () => {
  const array = ["a", "b", "c"];

  return (
    <main id="root">
      {array.map((el) => (
        <p key={el}>This is {el}</p>
      ))}
    </main>
  );
};
export default App;

Spread operator

The spread operator is not supported as a child jsx expression, so you are not able to put something like this to a react component:

 {...['a','b','c']}

Comments in JSX code

If you want to insert a comment to the react component, you need to wrap its using curly braces.

{
  /** this is comment */
}

JSX Styling

React encourages to use of inline styles. You can use JSX expressions to pass value to the style attribute to set inline styles. React will also automatically append px following the number of the specified property.

Note: inline styling is not the only way to style react elements. There are a few other approaches, but this is the topic for another article.

JSX: Conclusion

When you work on the React application, you can use JSX to put markup into javascript code. That means that you have HTML tags and JavaScript expressions in the same file.

Each JSX tag is transformed to React createElement javascript function. Moreover, If you don't want to use JSX for any reason, you can write react code without JSX.

In my opinion, JSX has many advantages, and definitely, it's a friend of any React developer. I love it the most in JSX because it looks like JavaScript with more power (It's fair to say that JSX is built on top of JavaScript). I like that approach more than something you can find in Vue.js or Angular, where you need to learn specific framework functions and syntax.

#WebDevelopment #FrontendDevelopment #JavaScript #React #JSX #ConceptExplanation #Tutorial #BestPractices #Intermediate

As a Magento Frontend developer (If you are not deal with Magento, you can skip this paragraph), you have a few mechanisms to customize the look and feel of your shops, like Layout modifications, customizing styles, or creating mixins). These methods (if you can use their power) allows you to do whatever you want with your shop.

Welcome to Magento PWA Studio

Magento PWA Studio was specially designed by the Adobe core team to help developers construct progressive web apps on Magento 2. This tool consists of ready-to-use, out-of-the-box solutions which are handy for headless storefronts development. The tool does have some benefits and weaknesses, including the value of the toolkits. In this article, I will show you one of the most powerful Magento PWA studio features: the extensibility framework.

PWA Studio extensibility framework

PWA Studio has a built-in extensibility framework for developers to extends the new storefront based on the Venia concept easily. Before introducing this solution, developers were forced to overwrite files using the webpack plugin. Overwriting core files causes unexpected errors and complicates the project. Each overwrites complicates everything and is harder. Thanks to PWA studio extensibility Framework you can reduce overwriters as much as possible.

Targetables

Regarding the https://marcin-kwiatkowski.com/blog/pwastudio/what-is-the-difference-between-pwa-studio-and-the-current-magento-frontend PWA, you also have a powerful mechanism for adding customizations called: targetables that allow you to modify the JSX output of your PWA (React) App during build-time. Targetables are part of the https://magento.github.io/pwa-studio/pwa-buildpack module.

Interceptor pattern

PWA Studio extensibility framework uses the Interceptor pattern to allow changes in PWA studio storefronts during code build time. That pattern allows you to modify code in a way that Magento PWA studio does know anything about that change. It means that you can enable/disable your piece of code and this is transparent for PWA Studio. Any changes in code are not necessary.

Take a look at how it works when you create a new project based on PWA Studio and want to add some changes there:

1. You scaffold a new project using pwa-buildpack CLI command-line instructions
2. You add a new module in the project directory, let's name it a @theme
3. You create an intercept file and put their instructions on which storefront parts you want to customize
4. You hook to specific targets that PWA Studio provides (I mean public API) to extend storefront by extensions/other modules
5. You use the public API provided by the pwa-buildpack module. For example, you use methods like insertAfterJSX, removeJSX, setJSXprops, and so on to achieve your goal
6. You can put all your extensions into one file, or have a few ones. Everything depends on you.
7. You run npm run build (or watch) and pwa-buildpack checks are there any interceptions exist and run those instructions.
8. If pwa-buildpack finds any error during build time, compilation fails, and errors are printed into the console.
9. Extensions are applied to the source code
10. Static code chunks contain modifications

Note about targetables in PWA studio extensions

When you create your own extension you are able to add targets that other extensions can intercept. Because of security reasons PWA Studio restricts the scope of Targetable modifications in extensions. So you can add modifications only within the source code of extensions. That means in the case when you create and publish an npm package and someone wants to use your module, interceptors from the module won't work automatically. You can prepare a public function, and consumers will be able to use it in their local-intercept.js file and then your extension will affect a storefront.

It's time to get your hands dirty

Enough of the theory. Let's see how it works in practice and create something using pwa-buildpack targetables!

Have you ever needed to add extra features to the Product Detail Page or wanted to customize it? I suppose the answer might be “yes” because the product page is probably the most frequently modified area in the online store.

In the following example, I would like to show you how to extend the product detail page into four steps:

• Get data from the API (define a /the-full-stack-guide-to-the-graphql-query query)

• Add Unit tests

• Create a component

• Inject the component to the Product Detail page

That process is repeatable for each customization you want to add to your store – however – in this article, we will work on a concrete case: how to add a short description to the product page.

Prerequisites

1. Scaffolded PWA Studio app - if you don’t know how to set up PWA Studio on your local – check out my video tutorial:https://youtu.be/lsiul60vBfs

2. Magento 2.4.2 installed locally - theoretically, you can use the public Magento instance with Venia sample data installed, but you cannot change anything in the admin panel. For example, you cannot change a product’s short description, so it will be hard to test the code.

Let’s go ride code!

Define a GraphQL query

The data comes from the Magento backend, and the only unknown thing is which GraphQL query we should use.

There is a products query:

products(
   search: String
   filter: ProductAttributeFilterInput
   pageSize: Int = 20
   currentPage: Int = 1
   sort: ProductAttributeSortInput
): Products

The products query searches for products that match the criteria specified in the search and filter attributes.

We definitely want to get one specific product and to achieve that I’m wanna use a product SKU as a filter. When you take a look at ProductAttributeFilterInput (of filter argument) you will see that there is an SKU field that we can use:

type ProductAttributeFilterInput {
    category_id: FilterEqualTypeInput
    category_uid: FilterEqualTypeInput
    description: FilterMatchTypeInput
    name: FilterMatchTypeInput
    price: FilterRangeTypeInput
    short_description: FilterMatchTypeInput
    sku: FilterEqualTypeInput
    url_key: FilterEqualTypeInput
}

Note for GraphQL beginners

When you run your local PWA Studio instance, you will see an URL to the GraphQl playground. There you can find docs with all necessary information about GraphQL schema and possible information (like the information I Listed above)

Let’s define the query in src / @theme / components / ShortDescription / ShortDescription.gql.js.

import gql from 'graphql-tag';

const GET_SHORT_DESCRIPTION_QUERY = gql`
    query shortDescriptionOfProduct($productSku: String!) {
        products(filter: { sku: { eq: $productSku } }) {
            items {
                uid
                short_description {
                    html
                }
            }
        }
    }


export default {
    queries: {
        getShortDescriptionQuery: GET_SHORT_DESCRIPTION_QUERY
    },
    mutations: {}
};

Of course, you can first use GraphQL Playground and write a query there, and when your query works as you want, you can just copy it to a source file in your project.

The query defined above takes one argument: product SKU, and it’s exported from the file as queries.getShortDescriptionQuery.

Define unit tests

In our case, we just need to check two things:

1. It is a short description visible when a product has it set up

2. It is a short description invisible when a product does not have a short description filled. (in this case, we assume that component will return null)

Let’s create a file src / @theme / components / ShortDescription / __tests__ / ShortDescription.spec.js and add tests to it. Before we start, please add necessary imports:

import React from "react";
import { render, getByText } from "@testing-library/react";
import { useQuery } from "@apollo/client";

import ShortDescription from "../ShortDescription";

jest.mock("@apollo/client");

Note about dependencies

You can see I use https://testing-library.com/docs/react-testing-library/intro/, so you need to add this as a dependency with other necessary dependencies. Also, you have to add config for jest to run tests. All of those things you can find in https://github.com/Frodigo/tutorial-pwa-studio-short-description. Describing that process is out of the scope of this tutorial, but please reach out to me on Magento Community Slack if you have any questions.

Memo about mocking

I mocked @apollo/client because I need to simulate communication with GraphQL API to test two scenarios I described earlier. Moreover, on the unit test level, we don’t want to test API.

I assumed that I would use the useQuery hook to fetch data from an API in my component.

Test one: it renders component when the short description is filled in a product

test("It renders component when the short description is filled in a product", () => {
  useQuery.mockReturnValue({
    data: {
      products: {
        items: [
          {
            uid: "1",
            short_description: {
              html: "<p>Lorem ipsum</p>",
            },
          },
        ],
      },
    },
  });

  const { container } = render(<ShortDescription productSku="abc" />);

  expect(getByText(container, "Lorem ipsum")).toBeDefined();
  expect(container).toMatchSnapshot();
});

I used useQuery.mockReturnValue function to define mocked returned value from API. Then I created an instance of ShortDescription component and passed “abc” value as the product SKU property (value is not essential here because returned data is mocked, so we need only to make sure that SKU is passed.

The next step is checking if Lorem ipsum text is rendered (defined). Take a look at the mock data - we returned the “lorem ipsum” paragraph there, so it should be rendered.

To check this, I used the getByText method of testing-library, which takes two arguments: container (tree, where we want to search, is passed value exists) and value (a value that we want to find in a specified container).

The function returns true if a value is defined in a container and false if not.

In the following line, we are just checking if rendered container matches the snapshot.

Test two: it does not render when a product does not have the short description

test("It does not render when a product does not have the short description", () => {
  useQuery.mockReturnValue({
    data: {
      products: {
        items: [
          {
            uid: "1",
            short_description: {
              html: "",
            },
          },
        ],
      },
    },
  });

  const { container } = render(<ShortDescription productSku="abc" />);

  expect(container.firstChild).toBeNull();
});

In the second case, there are two differences—the first one in another mocked data. The HTML field is empty.

The second one is to check that the rendered container is empty. I just check if container.firstChild is null.

Create the component

We have already declared unity tests, and they, of course, fail because the component that we test is not defined yet. Let’s create it by adding a file src / @theme / components / ShortDescription / ShortDescription.js with following content:

import React from "react";

import classes from "./ShortDescription.css";
import productOperations from "./ShortDescription.gql";

import { shape, string } from "prop-types";

const ShortDescription = (props) => {
  const { productSku } = props;
  const { queries } = productOperations;
  const { getShortDescriptionQuery } = queries;

  return <div className={classes.section}>Short description will be here</div>;
};

export default ShortDescription;

ShortDescription.propTypes = {
  classes: shape({
    root: string,
    section: string,
  }),
  productSku: string.isRequired,
};

From the beginning - we imported React because we want to create a React Component. Also, we imported a string checker from prop-types, and we use it to validate if productSku is passed:

ShortDescription.propTypes = {
  productSku: string.isRequired,
};

The productOperations object is imported from the already declared ShortDescription.gql.js file.

The classes object is the CSS module with classes. We imported it from src / @theme / components /ShortDescription / ShortDescription.css. Let’s create that file.

.root {
  margin: 15px 0;
}

.section {
  border-color: rgb(var(--venia-border));
  border-style: solid;
  border-width: 1px 0 1px;
  margin: 0 1.5rem;
  padding: 1.5rem 0;
}

Let’s back to the component file. You can see that we return static text:

return <div className={classes.section}>Short description will be here</div>;

Let’s make it dynamic!

Querying for data

The getShortDescriptionQuery is already imported, so now just import the useQuery hook from @apollo/client and use it to query data.

import { useQuery } from '@apollo/client';
(..)
const ShortDescription = props => {
(...)
 const { data } = useQuery(getShortDescriptionQuery, {
          fetchPolicy: 'cache-and-network',
          variables: {
              productSku
          }
     });
(...)

};

Note: Because I want to keep this example simple, I do not handle errors here.

Now we can use data returned by the useQuery hook. For example: data.products.items[0].short_description.html, but this is not perfect.

Save/memoize a short description

I have an idea: create a function that checks is a short description is defined and returns it. Otherwise return null.

I want to use the useMemo hook, which will memoize that value for us between re-renders of the component.

const shortDescription = useMemo(() => {
  if (!data) return null;

  const { products } = data;

  if (
    products &&
    products.items &&
    products.items.length &&
    products.items[0].short_description &&
    products.items[0].short_description.html &&
    products.items[0].short_description.html.length
  ) {
    return products.items[0].short_description.html;
  }

  return null;
}, [data]);

The shortDescription field will be changed only when data (passed in dependency array - the second argument of the useMemo) is changed.

Display short description

Let’s display a short description. Do you remember our test cases? If a description exists, we have to show it. Otherwise, we should return null.

Perfect, because our shortDescripotion constant has, in fact, two states: null or short description value.

We can use it to check what should be rendered. We will create the shouldRenderShortDescription constant that will yield a div contains a short description or return null.

BTW: the short description in the Magento backend is a WYSIWYG field, so the value returned from API is HTML. Let’s use the RichText component to render it:

import RichText from '@magento/venia-ui/lib/components/RichText';
(..)
const ShortDescription = props => {
(...)
const shouldRenderShortDescription = shortDescription ? <div className={classes.root}>
        <div className={classes.section}>
            <RichText content={shortDescription} />
        </div>
    </div> : null;

    return shouldRenderShortDescription;

}

Final component

Here is the finished source code of the ShortDesxcription component:

import React, { useMemo } from "react";
import { useQuery } from "@apollo/client";
import RichText from "@magento/venia-ui/lib/components/RichText";

import classes from "./ShortDescription.css";
import productOperations from "./ShortDescription.gql";

import { shape, string } from "prop-types";

const ShortDescription = (props) => {
  const { productSku } = props;
  const { queries } = productOperations;
  const { getShortDescriptionQuery } = queries;

  const { data } = useQuery(getShortDescriptionQuery, {
    fetchPolicy: "cache-and-network",
    variables: {
      productSku,
    },
  });

  const shortDescription = useMemo(() => {
    if (!data) return null;

    const { products } = data;

    if (
      products &&
      products.items &&
      products.items.length &&
      products.items[0].short_description &&
      products.items[0].short_description.html &&
      products.items[0].short_description.html.length
    ) {
      return products.items[0].short_description.html;
    }

    return null;
  }, [data]);

  const shouldRenderShortDescription = shortDescription ? (
    <div className={classes.root}>
      <div className={classes.section}>
        <RichText content={shortDescription} />
      </div>
    </div>
  ) : null;

  return shouldRenderShortDescription;
};

export default ShortDescription;

ShortDescription.propTypes = {
  classes: shape({
    root: string,
    section: string,
  }),
  productSku: string.isRequired,
};

The last thing related to the component is to create an index.js file that will export it.

Create a file src / @theme / components / ShortDescription / index.js

export { default } from "./ShortDescription";

Inject the component to the PDP

We have good progress so far – the ShortDescription component is ready to use, unit tests have passed. Let’s inject the component to a product detail page using targetables.

Add @theme dependency

Because of some unknown reasons, it’s not possible to use relative paths in the local-intercept.js file. The workaround for that is to create a virtual dependencyMagento using yarn link funcionality.

Add a new field to the “dependencies” array in PWA Studio root package.json:

"@marcinkwiatkowski/theme": "link:src/@theme"

Run yarn install command. When the install process is done, you should see the @marcinkwiatkowski/theme package in node_modules. When you make changes in the src/@theme directory, they will automatically apply in node_modules / @marcinkwiatkowski / theme directory.

Adding interceptor

Please replace local-intercept.js content with this one:

const { Targetables } = require("@magento/pwa-buildpack");

module.exports = (targets) => {
  const targetables = Targetables.using(targets);
};

Now, we are ready to use targetables.

Target the productFullDetail component

We want to add a short description between a title and quantity fields. After inspection, I figured out that the productFullDetail component is responsible for this area, so let’s handle it in the interceptor:

(...)
const targetables = Targetables.using(targets);

const ProductDetailComponent = targetables.reactComponent(
    '@magento/venia-ui/lib/components/ProductFullDetail/productFullDetail'
);

Import the ShortDescription component

Now we can add import to the productFullDetail component using targetables public API.

const ShortDescription = ProductDetailComponent.addImport(
  "ShortDescription from '@marcinkwiatkowski/theme/components/ShortDescription'",
);

Insert JSX

The last thing is to insert JSX in a specific place. Let’s add it after the section with class "title".

(...)
ProductDetailComponent.insertAfterJSX('<section className={classes.title} />', `<${ShortDescription} productSku={productDetails.sku} />`)

The exciting thing here is passing props. I passed productDetails.sku. To understand it, let’s imagine when that line is executed, the scope of data is the same as in intercepted component.

That means you can use all values which exist in the intercepted component. In this case, we are intercepting the productFullDetail component, and the productDetails object is available there.

Summary

I showed you the process of extending PWA Studio using targetables. We just used only one targetables method called insertAfterJSX, but there are a few more methods available.

Check out this article if you want to read more about targetables and other PWA Studio’s extensibility features.

Source code

I pushed the source code of this tutorial to my GitHub. You can find it here: https://github.com/Frodigo/tutorial-pwa-studio-short-description

There you can find all source files and scaffolded Magento PWA studio project. Just clone the code, install dependencies by running the yarn install command in the project directory and run the storefront-project by yarn run watch command.

#WebDevelopment #FrontendDevelopment #JavaScript #GraphQL #React #MagentoPWA #Apollo #Tutorial #DeepDive #ConceptExplanation #Intermediate #Testing #ComponentInjection #ExtensibilityFramework

A Category Landing Page is a special type of Category Page. In Magento, a Merchant can set unique content for a specific category. Take a look at this sample Magento Luma Category Landing Page.

How does it work

In the Magento category page configuration, there is a config field called Display Mode and there are three available options:

• Products only
• Static block only
• Static block and products

If you select the ‘Static block only’ option and set up a static block for the category, you will see your static block on the frontend for the Category, and this is precisely what the Category Landing Page means.

Does PWA Studio support Category Landing Pages?

No.

No.

No.

Is it possible to add support for CLP in PWA Studio?

If you read my blog….

Definitely YES.

Let’s do this!

Install PWA Studio

The very first thing that we need to do is create a new instance of PWA Studio

yarn create @magento/pwa
cd <directory where PWA Studio has been installed
yarn buildpack create-custom-origin ./

Also, we need to have our own Magento 2 instance. This time I am using Magento 2.4.2 with sample data installed. If you don’t have your own local Magento 2 installation, I recommend using https://github.com/markshust/docker-magento

People often ask me:

What is the best way to install Magento in the local environment?

Then I tell them:

Use Mark’s Docker – it’s the best

The Idea

To achieve our goal, we are going to use the PWA Studio Extensibility framework. We will create an improvedCategoryContent component which will be a wrapper for CategoryContent PWA Studio’s component. We will add additional logic there and display Category Landing page content instead of an empty page.

Implementation

Create theme

Before we start coding, let’s create a directory to keep all modifications related to the Category Landing Page.

First, create @theme/category folder in pwa_studio_root/src directory.

Second, let’s link this folder as a package in the package.json

dependencies": {
    "@magento/pwa-buildpack": "~9.0.0",
    "@theme": "link:src/@theme"
},

Add improvedCategoryContent component

Create file src / @theme / category / components / ImprovedCategoryContent / ImprovedCategoryContent.js with the following content:

import React from "react";
import PropTypes from "prop-types";

import CategoryContent from "@magento/venia-ui/lib/RootComponents/Category/categoryContent";
import LoadingIndicator from "@magento/venia-ui/lib/components/LoadingIndicator/indicator";
import { useImprovedCategoryContent } from "../../talons/useImprovedCategoryContent";
import CategoryLandingPage from "../CategoryLandingPage";

/**
 * The ImprovedCategoryContent wraps CategoryContent @components and allows to display Category Landing Pages
 * @param {object} props
 * @param {number} props.categoryId - Category's ID
 * @param {object} props.classes - additional CSS classes that will be applied to the component
 * @param {object} props.data - Category data
 * @param {object} props.pageControl - Pagination data
 * @param {number} props.pageSize - Page size
 * @param {object} props.sortProps - Sort props
 */
const ImprovedCategoryContent = (props) => {
  const {
    categoryId,
    classes,
    data,
    pageControl,
    sortProps,
    pageSize,
    ...rest
  } = props;

  const { isLandingPage, isLoading, staticBlockId } =
    useImprovedCategoryContent({ categoryId });

  const categoryContent = isLandingPage ? (
    <div>
      <CategoryLandingPage staticBlockId={staticBlockId} />
    </div>
  ) : (
    <CategoryContent
      categoryId={categoryId}
      classes={classes}
      data={data}
      pageControl={pageControl}
      sortProps={sortProps}
      pageSize={pageSize}
    />
  );

  const shouldDisplayContent = !isLoading ? (
    categoryContent
  ) : (
    <LoadingIndicator />
  );

  return <div {...rest}>{shouldDisplayContent}</div>;
};

ImprovedCategoryContent.propTypes = {
  categoryId: PropTypes.number.isRequired,
  classes: PropTypes.object,
  data: PropTypes.object,
  pageControl: PropTypes.object,
  pageSize: PropTypes.number,
  sortProps: PropTypes.array,
};

export default ImprovedCategoryContent;

The purpose of this component is to check if the category page is a category landing page. All logic related to checking that is in useImprovedCategoryContent hook that we will create in the next step.

If the category is a landing page, the CategoryLandingPage component is rendered. Otherwise, native PWA Studio’s CategoryContent will be rendered.

Next, create the src / @theme / category / components / ImprovedCategoryContent / index.js file with following content:

export { default } from "./ImprovedCategoryContent";

Add GET_CATEGORY_LANDING_PAGE query Before implementing the hook, let’s create a /the-full-stack-guide-to-the-graphql-query that will get information about category display mode and a Static Block ID used for a category’s content.

Create a src/@theme/category/queries.gql.js file:

import gql from "graphql-tag";

export const GET_CATEGORY_LANDING_PAGE = gql`
  query category($id: Int!) {
    category(id: $id) {
      id
      display_mode
      landing_page
    }
  }
`;

The query is really straightforward. One important thing here is the ID field in results. Thanks to that ID, Apollo Client can merge these query results with other queries by ID.

Records are merged by ID, and if you have three queries for a category with the same ID, results will be stored in Apollo cache and available without querying to the server. How powerful is that?

Add useImprovedCategoryContent hook

Create a src / @theme / category / talons / useImprovedCategoryContent.js file:

import { useQuery } from "@apollo/client";
import { GET_CATEGORY_LANDING_PAGE } from "../queries.gql";

/**
 * Returns props necessary to render the ImprovedCategoryContent @component.
 *
 * @param {object} props
 * @param {number} props.categoryID
 *
 * @returns {string} result.error - error message returns if something went wrong
 * @returns {bool} result.isLandingPage - flag determinates is a Category is in Statick Blocks only mode.
 *                                        This is true when display mode eauals 'PAGE'
 * @returns {bool} result.isLoading - flag determinates is data loading
 * @returns {number|null} result.staticBlockId - Static block ID set up for the Category Page or null.
 */
export const useImprovedCategoryContent = (props) => {
  const { categoryId } = props;

  const { data, loading } = useQuery(GET_CATEGORY_LANDING_PAGE, {
    fetchPolicy: "cache-and-network",
    nextFetchPolicy: "cache-first",
    variables: {
      id: categoryId,
    },
  });

  return {
    isLandingPage: data && data.category.display_mode === "PAGE",
    isLoading: loading,
    staticBlockId: data ? data.category.landing_page : null,
  };
};

Note: Because I want to keep this example simple, I do not handle errors here.

That hook receives one parameter - categoryId, and it gets data from the Magento backend using the already declared GET_CATEGORY_LANDING_PAGE query.

Hook returns three fields:

• isLandingPage - this flag determines category is a landing page or not. Each category that has set up Display Mode equals Page is a landing page.

• isLoading - determines state of data loading

• staticBlockId - ID of static block set up for Category landing page.

Update local-intercept.js

It’s time to inject our component into Storefront. Take a look at the code below. If you are not familiar with PWA Studio extensibility framework, check https://marcin-kwiatkowski.com/blog/pwastudio/how-to-extend-pwa-studio-with-new-features.

File src/local-intercept.js:

const { Targetables } = require("@magento/pwa-buildpack");

module.exports = (targets) => {
  const targetables = Targetables.using(targets);

  const CategoryRootComponent = targetables.reactComponent(
    "@magento/venia-ui/lib/RootComponents/Category/category",
  );

  const ImprovedCategoryContent = CategoryRootComponent.addImport(
    "ImprovedCategoryContent from '@theme/category/components/ImprovedCategoryContent'",
  );

  CategoryRootComponent.replaceJSX(
    "<CategoryContent />",
    `<${ImprovedCategoryContent} />`,
  ).setJSXProps(`ImprovedCategoryContent`, {
    categoryId: "{id}",
    classes: "{classes}",
    data: "{categoryData}",
    pageControl: "{pageControl}",
    sortProps: "{sortProps}",
    pageSize: "{pageSize}",
  });
};

To insert the ImprovedCategoryContent component, we added import to the Category root component. We used the replaceJSX method to insert the component to the JSX (replace the native component with our new one). We passed all props from the native component to ours.

Add CategoryLandingPage component

First, create a file src / @theme / category / components / CategoryLandingPage / CategoryLandingPage.js with the following content:

import React from "react";
import PropTypes from "prop-types";
import PlainHtmlRenderer from "@magento/venia-ui/lib/components/RichContent";
import LoadingIndicator from "@magento/venia-ui/lib/components/LoadingIndicator/indicator";

import { useCategoryLandingPage } from "../../talons/useCategoryLandingPage";
import classes from "./CategoryLandingPage.module.css";

/**
 * The CategoryLandingPage @component displays CMS content for categories that have set up Display mode to Static block only.
 *
 * @param {object} props
 * @param {string} props.staticBlockId - Static block's ID that provides content for the Page
 */
const CategoryLandingPage = (props) => {
  const { staticBlockId, ...rest } = props;

  const { content, errorMessage, isLoading } = useCategoryLandingPage({
    staticBlockId,
  });

  const shouldDisplayContent = !isLoading ? (
    <PlainHtmlRenderer html={content} />
  ) : (
    <LoadingIndicator />
  );
  const shouldDisplayError = errorMessage ? <p>{errorMessage}</p> : null;

  return (
    <div className={classes.categoryLandingPage} {...rest}>
      {shouldDisplayContent}
      {shouldDisplayError}
    </div>
  );
};

CategoryLandingPage.propTypes = {
  staticBlockId: PropTypes.string.isRequired,
};

export default CategoryLandingPage;

Keep in mind the component is rendered if a category has display mode equals Page set up. The component receives staticBlockId prop and uses it to get content for a specific category.

Content is rendered using PlainHtmlRenderer. If something went wrong, an error message is rendered.

Second, create a file src / @theme / category / components / CategoryLandingPage / index.js:

export { default } from './CategoryLandingPage';

Lastly, create a CSS module src /@theme / category / components / CategoryLandingPage / CategoryLandingPage.module.css

.categoryLandingPage {
  padding: 20px;
}

Add useCategoryLandingPage hook

The last thing needed to display the Category landing page’s content is the hook that collects content from Magento.

Create a file src / @theme / category / talons / useCategoryLandingPage.js:

import { useState, useEffect } from 'react';
import { useQuery } from '@apollo/client';
import { GET_CMS_BLOCKS } from '@magento/venia-ui/lib/components/CmsBlock/cmsBlock.js';

/**
 * Returns props necessary to render the CategoryLandingPage @component.
 *
 * @param {object} props
 * @param {number} props.staticBlockId - ID of a Static Block connected with the Category Landing Page
 *
 * @returns {string} result.errorMessage - error message returns if something went wrong
 * @returns {bool} result.isLoading - flag determinates is data loading
 * @returns {string} result.content - HTML content of Static Block connected to the Category Landing Page
 */
export const useCategoryLandingPage = props => {
    const {
        staticBlockId
    } = props;

    const [ content, setContent ] = useState(null);
    const [ errorMessage, setErrorMessage ] = useState(null);

    const { data, error, loading } = useQuery(GET_CMS_BLOCKS, {
        fetchPolicy: 'cache-and-network',
        nextFetchPolicy: 'cache-first',
        skip: !staticBlockId,
        variables: {
            identifiers: [ staticBlockId ]
        }
    });

    useEffect(() => {
        if (data && data.cmsBlocks && data.cmsBlocks.items) {
            setContent(data.cmsBlocks.items[0].content);
        }

        if (!staticBlockId || error || data && data.cmsBlocks && data.cmsBlocks.items.length === ) {
            setErrorMessage('Unable to get category page content. Please try again later.')
        }

    }, [data, staticBlockId, error])

    return {
        errorMessage,
        isLoading: loading,
        content
    }
}

The component returns three fields, and the most important for us is content, which contains the Category Landing page’s content!

Summary

This time we added support for Category Landing Pages to PWA Studio Storefront. As you can see, the PWA Studio Extensibility framework is really powerful, and thanks to this we can easily extend https://marcin-kwiatkowski.com/blog/pwastudio/getting-started-with-magento-pwa-studio-targetables with new features.

Source code

The source code for this tutorial is available on my https://github.com/Frodigo/pwa-studio-category-landing-pages

#WebDevelopment #FrontendDevelopment #BackendDevelopment #JavaScript #CSS #GraphQL #React #PWAStudio #Magento #Apollo #Tutorial #DeepDive #ProjectSetup #Intermediate #API #ComponentArchitecture

This time I would like to show you how to extend PWA Studio with new features. After reading you will know the following:

• What is the PWA Studio’s extensibility framework and what tools/techniques it offers

• How to extend the PWA Studio storefront

• How to create a new PWA Studio module

• How to customize PWA Studio storefront’s styles

PWA Studio extensibility framework

PWA Studio extensibility framework is a set of tools that helps developers to extend storefronts in a smart way.

What does that mean? For me extension is smarty if it adds something to the app without core code overwriting, for example:

• adding a new payment method without overwriting any checkout core files - this is smart

• adding a short description to a product page without overwriting a bunch of components including the product root component - this is also cute

• to overwrite the JS and CSS file of one of the components to change the look of it - this is totally thoughtless

Overwriting core files causes unexpected errors and complicates a project. Each overwrite complicates everything more and more and whatever you want to do in the project with a huge amount of overwrites is hard to do.

if you had overwritten too much in your project you would have looked like the guy on the image.

Thanks to the PWA Studio extensibility framework you can minimize the amount of overwriting to a minimum.

Note: We are talking about PWA Studio 9 introduced targetables. Thanks to this, extending PWA Studio with the new features is possible without overwriting core code. In previous versions of PWA Studio, it was not possible in general, and keep in mind that many of my articles and tutorials are deprecated now and I need to update them.

Targets

One of the options to extend PWA Studio is to use Targets.

How it works:

• Using interceptor pattern to modify core behavior by modifying core code output during build time.

• the point that you can intercept the normal logic is Targets

• targets are variants of a JavaScript pattern called Tappable hook

• targets share some functionality with NodeJS’s EventEmitter class

TargetProviders

The TargetProvider is an object that provides public API to create targets and intercepting targets from other extensions.

For example, you can use routes Targets to add a new route. In this case, you create an intercept.js file in use "routes" target to add a new route to your storefront.

// intercept.js
module.exports = targets => {
    const veniaTargets = targets.of('@magento/venia-ui');
    const routes = veniaTargets.routes;

    routes.tap(
      routesArray => {
         routesArray.push({
             name: 'New route',
             pattern: '/new-route',
             path: '@organization/module'
         });
         return routesArray;
      })
}

// package.json
{
  "pwa-studio": {
    "targets": {
      "intercept": "intercept.js"
    }
  }
}

Targetables

Another method to customize PWA Studio is using targetables which are object which represents source files in your projects.

Thanks to targetables you can for example get a specific component and insert JSX wherever you want. Take a look at the example below:

const { Targetables } = require("@magento/pwa-buildpack");

module.exports = (targets) => {
  const targetables = Targetables.using(targets);

  const MainComponent = targetables.reactComponent(
    "@magento/venia-ui/lib/components/Header/header.js",
  );

  MainComponent.insertAfterJSX("<MegaMenu />", "<div>My new section!!</div>");
};

On the other hand, if you create your own PWA Studio extension you can use Targetqables to add specific targets for other modules.

How to customize PWA Studio

Typically if you deal with PWA Studio you create a new Storefront or a new extension.

Creating a new storefront

The first option to extend PWA Studio with new features is by creating a new storefront. Venia concept can be your starting point, but it’s not obligatory. Typically you will start from the Venia concept because it has many excellent features already implemented. In this case, you start by scaffolding your project using the yarn create @magento/pwa command. Then you have the opportunity to add customizations.

Take a look at an example scenario when you want to add a new section to the product page. Let’s add lorem ipsum text before Add to cart button.

First, scaffold the PWA Studio project:

yarn create @magento/pwa
cd <project_dir>
yarn run buildpack create-custom-origin
yarn run watch

Second, add this code to the local-intercept.js file:

const { Targetables } = require("@magento/pwa-buildpack");

module.exports = (targets) => {
  const targetables = Targetables.using(targets);

  const ProductFullDetailComponent = targetables.reactComponent(
    "@magento/venia-ui/lib/components/ProductFullDetail/productFullDetail.js",
  );

  ProductFullDetailComponent.insertBeforeJSX(
    '<Button type="submit" />',
    "<span>Hello World! </span>",
  );
};

This code inserts a span with Hello World! Before submit button of the add to cart form.

Targetables public API

In the example above, I used insertBeforeJSX method of@magento / pwa-buildpack / lib / WebpackTools / targetables / TargetableReactComponent.js

There are a few more public methods available that help you with modifying the PWA Studio storefront:

• insertAfterJSX - Inserting a JSX element _after_ `element`.

• addJSXClassName - Adding a CSS classname to a https://marcin-kwiatkowski.com/blog/what-is-jsx-and-is-it-worth-making-friends-with-it element.

• addReactLazyImport - Add a new named dynamic import of another React component

• appendJSX - Appending a JSX element to the children of `element`

• prependJSX - Prepending a JSX element to the children of `element`.

• removeJSX - Removing the JSX node matched by 'element'.

• removeJSXProps - Removing JSX props from the element if they match one of the lists of names.

• replaceJSX - Replacing a JSX element with a different code.

• setJSXProps - Setting JSX props on a JSX element.

• surroundJSX - wrapping a JSX element in an outer element.

As you can see, those JSX manipulations are powerful and let you do whatever you want.

Creating a new extension

Another way to customize PWA Studio is by creating a new extension. For example, if you had wanted to add integration with any headless CMS systems, you would have to create a new extension.

Everyone who wants to use your extension can install it and use it in his project. This also means that any extension can be extended in storefronts where it’s used.

As an extension creator, you can use Targetables in your intercept file to add specific Targets that are available to other extensions.

I recommend using https://github.com/larsroettig/create-pwa-studio-extension to create new PWA Studio extensions.

You can create an extension using one command:

$ yarn create @larsroettig/pwa-extension

Then you need to link your extension in the package.json file of the PWA Studio project and you can work on it.

If you want to read more about creating extensions please check https://marcin-kwiatkowski.com/how-to-build-a-high-quality-pwa-studio-extension

Styling PWA Studio

The common thing that frontend developers do is styling. In terms if you want to customize styles of the Storefront you need to add your custom styles somewhere.

Thanks to Targetables styling PWA Studio is much more simplified than before. Chris Brabender wrote a fascinating article about this.

You can find it here: https://dev.to/chrisbrabender/simplifying-styling-in-pwa-studio-1ki1

Summary

Since PWA Studio 9.0.0 developer experience is much better, there is a public API called Targetables that gives developers an easy way to customize PWA Studio Storefronts.

Thanks to that, you can manipulate JSX output and develop high-quality storefronts/extensions.

Besides that, there is the Targets API that allows, for example, to create a new storefront routes or new content renderers in 1 minute without any overwrites.

All of these goods make PWA Studio a great starting point for any new headless projects connected with the Magento backend.

Sources

• https://magento.github.io/pwa-studio/pwa-buildpack/extensibility-framework/

• https://en.wikipedia.org/wiki/Interceptor_pattern

• https://github.com/webpack/tapable

• https://magento.github.io/pwa-studio/venia-ui/reference/targets/#routes--tapableasyncserieswaterfall

#WebDevelopment #FrontendDevelopment #JavaScript #JSX #React #PWAStudio #Magento #Webpack #ConceptExplanation #Tutorial #BestPractices #Intermediate #Extensibility #CustomizationTechniques

CSS is easy, right?

I started my web developer journey as a frontend developer, and with time I also started to deal with backend employees. My colleagues from the backend team were laughing that CSS is just a language for just setting margins and colors.

Keep in mind: if you do something more than adding color to headings…

CSS is not easy.

Take a look at the list below. The biggest CSS dangers are described here:

1. Conflicts between CSS rules

2. Overwrites

3. A big CSS stylesheet with unused rules

4. Side effects

CSS modules to the rescue

Thanks to the fact that CSS modules are scoped locally, the problems described above disappear.

• no more conflicts

• no side effects

• no global scope

An example CSS module

Take a look below at a straightforward example of a CSS module in https://marcin-kwiatkowski.com/blog:

CSS module (this is just a CSS file)

.section {
  padding: 15px;
}

.heading {
  font-size: 24px;
  font-weight: bold;
  margin: 15px 0;
}

The sample component which uses these styles

import React from "react";
import classes from "./sample-component.css";

const SampleComponent = () => {
  return (
    <div className={classes.section}>
      <h3 className={classes.heading}>This is the sample component title</h3>
      <p>This is the sample component paragraph</p>

      <h4 className={classes.heading}>This is the sample list:</h4>
      <ul>
        <li>Sample item A</li>
        <li>Sample item B</li>
        <li>Sample item C</li>
      </ul>
    </div>
  );
};

export default SampleComponent;

On the third line, we imported a CSS module called sample-component.css as a classes object. Now we are able to use classes from the CSS module as object properties. Take a look at lines 6,7, and 10.

So this is exactly what CSS modules do—they let you use CSS classes as object properties in https://marcin-kwiatkowski.com/blog/what-is-jsx-and-is-it-worth-making-friends-with-it files.

How does it work?

Thanks to Webpack and the configuration of the loaders, the classes described in the CSS module, and applied in the React component, are rendered as unique CSS classes for each place where they are used.

1. Here is the place where the section class is applied to the node.

2. This is a CSS rule which includes CSS properties.

3. Here you can see a unique class name applied to the node in the compiled app.

4. This is compiled into a unique CSS rule.

Webpack configuration

Take a look at the webpack configuration. In PWA Studio you can find them in @magento / pwa-buildpack / lib / WebpackTools / configureWebpack / getModuleRules.js file

getModuleRules.css = async ({ paths, hasFlag }) => ({
  test: /\.css$/,
  oneOf: [
    {
      test: [paths.src, ...hasFlag("cssModules")],
      use: [
        "style-loader",
        {
          loader: "css-loader",
          options: {
            localIdentName: "[name]-[local]-[hash:base64:3]",
            modules: true,
          },
        },
      ],
    },
    {
      include: /node_modules/,
      use: [
        "style-loader",
        {
          loader: "css-loader",
          options: {
            modules: false,
          },
        },
      ],
    },
  ],
});

On line 11 you can see where the names of the compiled classes come from, and line 12 is where the CSS modules are enabled.

Composition

CSS modules let you compose rules from other rules:

.heading {
  font-size: 24px;
  font-weight: bold;
  margin: 15px 0;
}

.secondaryHeading {
  composes: heading;
}

It’s possible to compose multiple selectors:

.section {
  padding: 15px;
}

.header {
  background-color: lightgray;
}

.heading {
  font-size: 24px;
  font-weight: bold;
  margin: 15px 0;
}

.secondaryHeading {
  composes: heading;
}

.sampleHeader {
  composes: section header heading;
}

Global CSS Rules

Scoping styles locally is lovely, but sometimes you need to define some global CSS rules, for example for animations (keyframes). CSS modules let us create global rules using the :global() function.

// global-styles.css
:global(.global-class-name) {
  color: red;
}

When you import this CSS module into your app, you will be able to use a global CSS rule like this:

// import stylesheet
import './global-styles.css'
...
// example of using global CSS rule
<p className="global-class-name">This is paragraph with global styles appiled</p>

Composing from global

Sometimes it is necessary to compose from a global rule to a local one, which you can do like this:

.redHeading {
  composes: global-class-name from global;
}

Naming conventions

It’s recommended to use the camel case naming convention because using classes in JS, in this case, is easiest. When the name of the class looks. for example, like this: .my-sample-class, then you can apply this class to an element in the following way:

<ul className={classes['my-sample-class']}>

Merging and overrides classes

In PWA Studio you can pass classes as props to a component, and overwrite default component classes with classes from props. Take a look:

import { mergeClasses } from '@magento/venia-ui/lib/classify';
import defaultClasses from '@magento/venia-ui/lib/components/Main/main.css';

const Main = props => {
   const classes = mergeClasses(defaultClasses, props.classes);
}

If you pass classes as props, you can validate them using PropTypes:

Main.propTypes = {
  classes: shape({
    page: string,
    page_masked: string,
    root: string,
    root_masked: string,
  }),
};

Conclusion

In my opinion, locally scoped CSS resolve many problems and is a really nice, modern approach to managing styles. Perhaps for many Frontend Developers, this is a controversial approach, and that’s OK because this is completely different from what is commonly used.

Maybe you have experience with CSS modules? Let me know in the comments!

Thanks for reading. All likes, shares, and comments are really appreciated.

Github repository

You can find examples of the code for this article on my Github.https://github.com/Frodigo/css-modules-examples-pwa-studio

Sources

https://magento.github.io/pwa-studio/technologies/basic-concepts/css-modules/

https://github.com/css-modules/css-modules

https://webpack.js.org/loaders/css-loader/#modules

https://x-team.com/blog/css-modules-a-new-way-to-css/

https://glenmaddern.com/articles/css-modules

#WebDevelopment #FrontendDevelopment #JavaScript #CSS #React #Webpack #PWAStudio #JSX #ConceptExplanation #Tutorial #BestPractices #Intermediate #ModularDesign

This change will be a big challenge for frontend developers because working with PWA Studio is entirely different from working with the current Magento frontend. This change will be a big challenge for frontend developers because working with PWA Studio is entirely different from working with the current Magento frontend. The technology stack used is completely different. Therefore, different competencies and skills are required. In this article, I would like to show you the differences between the two and compare the current Magento frontend technology stack with that of PWA Studio.

Prerequisites

The most crucial difference is that the PWA Studio is a typical React app, and you don't need special knowledge about Magento to get started with PWA Studio development.

Do you know React?

Do you know GraphQL and Apollo?

If yes, You are ready to go!

On the other hand – because it's a React App – the typical Magento Frontend Developer will have problems getting started.

You may ask, why?

In my opinion, Magento frontend devs are not familiar(no all!) with advanced JavaScript patterns and methodologies. They work with jQuery on daily basics, sometimes with KnockoutJS.

Understanding Magento JavaScript development is quite challenging and forces you to learn specific patterns that only Magento uses.

That is the main reason why there are not too many frontend Magento developers. Almost nobody wants to learn Magento-specific stuff (who wants to use KnockoutJS in 2021, BTW?)

I had a problem returning to the "normal world" after a few years with Magento frontend development and learn React.

Ok, this was only an introduction. Take a look at the differences between Magento-monolithic frontend and PWA Studio below.

Theme vs. Application

The current Magento frontend is built based on themes. There are two primary themes (Blank and Luma) that you can inherit from. The Luma theme inherits from the Blank theme, and the Blank theme overrides files from core Magento modules.

Theme code is placed in the Magento structure, and it is a part of a project. Moreover, it's possible to create modules and manage frontend customization directly in module code.

PWA Studio uses an entirely different approach. Have you heard about headless? First of all, this means that the storefront is separated from the backend. This is the right approach because the frontend developer environment is faster and more straightforward. A Magento instance can be set up in a different place entirely. In this case, the frontend team and the backend team are independent, and developing software is more comfortable for both sides.

The only important thing when it comes to using a headless storefront with the Magento backend is data such as products, customer data, shopping cart, etc. All this data is retrieved from Magento using GraphQLqueries (it is also possible to use the REST API to get data from the backend if The GraphQL API is not available for a particular functionality).

One of the most significant advantages of using GraphQL is that a frontend developer can quickly mock sample data, and switch to real data when the backend is done.

Inheritance vs. modularity

When working with a Magento theme, frontend developers typically override templates, layouts, JS and CSS/Less files from the parent themes or modules. With multi-level inheritance and a large number of modules, a minor change can quickly become complicated.

The PWA Studio storefront is quite different and requires frontend developers to build a storefront from scratch using ready-made React components, or by making their own. PWA Studio is simply a collection of tools that are designed to facilitate your storefront development. Take a look below at the most essential parts of PWA Studio.

Peregrine

This library gives developers a set of functions responsible for providing data to visual components in their application. This is mostly achieved through hooks and talons. You may be wondering what 'talons' means. Talons are a specific type of hook, which are designed for particular components. For example, the useFooter talon is designed to be used with the footer component and provide it with copyright text.

import { useEffect } from "react";
import { useQuery } from "@apollo/react-hooks";

/**
 *
 * @param {*} props.query the footer data query
 */
export const useFooter = (props) => {
  const { query } = props;
  const { error, data } = useQuery(query);

  useEffect(() => {
    if (error) {
      console.log("Error fetching copyright data.");
    }
  }, [error]);

  return {
    copyrightText: data && data.storeConfig && data.storeConfig.copyright,
  };
};

Venia UI API

his is a set of visual components that you can use when building a storefront. Within this set you will find a few base components, for example, Button, ButtonGroup, Logo.

Venia Storefront (Concept)

This is a storefront built using Peregrine and Venia UI. This is a storefront demo that presents the capabilities of PWA Studio. It can be the starting point of your application, but it doesn't have to be. Anyway it provides support for many Magento features and a few ways to extensibility.

Developer skill set comparison

I wanted to give this section the title: "Frontend Developer skill set comparison," but sometimes, when I think about Magento Frontend Developers, I get confused, because they need to be familiar with a few non-frontend technologies like PHP and XML. I believe that for more experienced frontend developers, the right career path will be working towards becoming a Full Stack Magento Developer.

But not everyone wants to work this way, and it is not surprising that not every frontend developer will want to learn PHP. Here, PWA Studio has an advantage because it uses typical frontend tools and technologies, which are more friendly for frontend developers. Take a look at the table below where you can find a comparison of the technologies and tools used in a typical Magento frontend and in PWA Studio.

JavaScript ES5 vs. JavaScript ES6

In PWA Studio, the ES6 version of JS is standard, while Magento still uses ES5. I think that for every JavaScript developer, writing code in a newer standard is a meaningful advantage. It is true that you can also write in ES6 while working on the Magento frontend, if you take care of compilation to ES5 (I recommend using Snowdog Frontools for this). The problem is that this is a solution for new code only. You still need to remember that all of the core JavaScript code in Magento is written using the old standard, and you just have to live with it.

Grunt vs. Webpack

The Magento frontend uses Grunt as a task runner. A frontend developer can compile Less files and run unit tests using Grunt, but in fact, using Grunt is not necessary. For example, a developer can compile styles using a client-side compilation workflow. PWA Studio uses Webpack, and this tool is very different to Grunt. Webpack is a module bundler, and it is responsible for compiling the whole PWA Studio application.

Less vs. CSS modules

CSS modules are an interesting approach. The key feature is that all styles are used locally, i.e., within one component. This is an entirely different approach from the current Magento frontend, where styles are global.

Knockout, jQuery, Magento UI components vs. React

In my opinion, the Magento frontend's biggest problem is that there is a mix of technologies and this results in chaos. Famous UI Components – a result of the Magento Core Team's imagination – are a combination of JavaScript, PHP, and XML, and digging deeper, it turns out that Knockout is mixed with jQuery. It turns out that Knockout is mixed with jQuery.

In PWA Studio, React is used, and the best thing is that a Frontend developer doesn't need to know PHP, XML, or any other non-frontend tools and technologies.

Magento templates vs. https://marcin-kwiatkowski.com/blog/what-is-jsx-and-is-it-worth-making-friends-with-it

Also, there is another type of template that is used by Magento UI Components. These templates are written as HTML files, and within them, you can find static HTML code mixed with KnockoutJS bindings.

Now, just as a comparison, take a look at an example piece of code for a PWA Studio view component:

Summary

PWA Studio is different from the current Magento frontend in every area. The most significant advantage (for developers) is that PWA Studio is more developer-friendly. This is the future for Magento Frontend developers, and I am keeping my fingers crossed for this project. Also, keep in mind that there are alternatives to PWA Studio, for example: Vue Storefront. So maybe PWA technology is the future of e-commerce? What do you think? Feel free to post comments.

Sources

• https://magento.github.io/pwa-studio/technologies/theme-vs-storefront/

• https://magento.github.io/pwa-studio/peregrine/

• https://github.com/magento/pwa-studio/tree/develop/packages/peregrine/lib/talons

• https://www.smashingmagazine.com/2020/04/react-hooks-api-guide/

• https://magento.github.io/pwa-studio/venia-ui/reference/components/Button/

• https://stackshare.io/stackups/grunt-vs-gulp-vs-webpack

• https://github.com/css-modules/css-modules

#WebDevelopment #FrontendDevelopment #Ecommerce #JavaScript #PHP #CSS #React #GraphQL #Apollo #KnockoutJS #jQuery #Webpack #Grunt #Magento #PWAStudio #Comparison #ConceptExplanation #BestPractices #Intermediate #Headless #ProgressiveWebApps