Forem: Ruben Suet

Bind properties in a NextJS server action form and useFormState

Ruben Suet — Wed, 14 Feb 2024 15:31:52 +0000

NextJS suggests you how to bind properties in server actions when working with forms. As well they suggest how to listen to the status of your form once you submit with useFormState. However, how can you bind data AND useFormState together?

The order matters; in this case, you have to bind first, and then wrap it with useFormState.

import { updateServerAction } from './server-actions';

export function UpdateForm({id}: {id: number}) {
  const updateWithId = updateServerAction.bind(null, id)
  const [state, formAction] = useFormState(updateWithId, {
    message: '',
  });

  return (
    <form action={formAction}>
     ... my code
    </form>
  )
}

Now when invoking the server action, it can go in the following order:

"use server"

export async function updateServerAction(id: number, prevState: {message: string}, form: FormData) {
  // code
}

This is quite useful for forms where you need to pass data but you don't want to expose it as hidden fields in the form itself. With this technique now it is possible to listen to the status of the useFormState and pass data to the server without exposing it in the form.

Unleashing the Power of Spring Boot and Kotlin: Modernizing API Authorization Part III

Ruben Suet — Wed, 15 Nov 2023 08:44:32 +0000

In the previous articles, I discussed the implementation of a login system in a Spring Boot app using Spring Security and demonstrated how to implement JWT for authenticating users and granting access to specific endpoints. In this final article, we'll explore how to eliminate the InMemoryUserDetailsManager and transition to our custom User model, integrated with our database.

This article is your guide to mastering three key aspects in three parts:

Login via API: We'll kick things off by tackling the initial API login.
Implementing a JWT for Persistence: Learn how to keep your users authenticated via API using the shiny new JWT.
Connecting Database Users to Spring Security: Dive into the realm of syncing your database users seamlessly with the Spring Security system.

Integrating Database Users with Spring Security

Currently, our application hosts a pre-established user with a designated username and password. While this setup is perfectly suitable for testing or small-scale proof-of-concept applications, in many instances, we want to take a more comprehensive approach and take control over the user data stored in our database. It is assumed in this tutorial that you have successfully established a connection to a database, ensuring that works correctly. The examples in this tutorial will be demonstrated using MySQL and JPA; however, you can easily adapt the instructions to your chosen stack, such as MongoDB or opting for JDBC over JPA.

Here is the Data Definition Language (DDL) employed for our users:

CREATE TABLE IF NOT EXISTS users (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(25),
    password TEXT
)

For managing database migrations, I recommend usin a version control system such as Flyway. A detailed tutorial on Flyway can be found here.

Note that our user entries are without any extra information. This tutorial doesn't require additional details, but feel free to add any fields you need (like email, street, phone). It's essential to emphasize that this schema doesn't include any role (the authorization part of Spring Security) as it's a topic not covered in this tutorial.

With all our configuration placed in the security package before, let's proceed to create a new package called user to establish a User model.

`User.kt`

@Entity
@Table(name = "users")
class User(
    @Column(nullable = false)
    private val username: String,
    private val password: String
): UserDetails {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long = 0


    override fun getAuthorities(): MutableCollection<out GrantedAuthority> {
        return mutableListOf(SimpleGrantedAuthority("USER"))
    }

    override fun getPassword(): String {
        return password
    }

    override fun getUsername(): String {
        return username
    }

    override fun isAccountNonExpired(): Boolean {
        return true
    }

    override fun isAccountNonLocked(): Boolean {
        return true
    }

    override fun isCredentialsNonExpired(): Boolean {
        return true
    }

    override fun isEnabled(): Boolean {
        return true
    }

}

This model is annotated with @Entity, and I've specified the @Table name. I added the username and password in the primary constructor, while keeping the ID outside of it and initialized it as 0. The database will manage the ID, and it's not our responsibility to manage this field. If a new User is created, it can go straight as User("username", "password") rather than User(null, "username", "password").

This class implements the UserDetails interface, which establishes the connection needed between the security framework and your model. The methods implemented are a requirement from this interface.

For getPassword and getUsername, we provide this information, allowing the AuthenticationFilter to retrieve the info when needed. Regarding getAuthorities, it's related to the roles a user can have for the authority part. Since we're not covering this topic in these articles, we simply return a list with a unique role called "USER."

All the methods starting with is* are eventually called by the filter chain to check user information for granting authentication or authorization. For simplicity, all of them return true, and this topic is not explored in the tutorial. As an example, consider isAccountNonLocked; we could record in the database the wrong login attempts for the user. If it exceeds a certain threshold, we could return false, locking the user account and allowing login after a specified period.

With UserDetails implemented, it's time to create a repository that connects the model and the database. In the user package:

`UserRepository.kt`

Interface UserRepository: ListCrudRepository<User, Long> {
    fun findByUsername(username: String): Optional<User>
}

With JPA 3.X, the interfaces from JPA have slight differences, and ListCrudRepository now implements the same methods as CrudRepository but returns a List type instead of Iterable. Here is the schema of interfaces for JPA 3:

Now, the last part of our connection with Spring Security is missing: how the filters can find the user from our DB. We have the repository, but there's no implementation to let Spring Security know that it should use this repository for finding users. Here comes our last file in the user package:

Here's the final part of our user configuration for Spring Security: the UserDetailsService implementation.

`UserService.kt`

@Service
class UserService(private val userRepository: UserRepository) :UserDetailsService {
    override fun loadUserByUsername(username: String): UserDetails {
        return userRepository.findByUsername(username).orElseThrow { RuntimeException("User Not Found") }
    }
}

This class implements the UserDetailsService, requiring the implementation of the loadUserByUsername function. In this method, we inject our repository and use the findByUsername method we created. If the user is not found, we throw a new error.

One last detail remains to be addressed. In the config file, we previously created an in-memory user:

`SecurityConfig.kt`

  @Bean
  fun userDetailsService(): UserDetailsService {
     val user = User.withDefaultPasswordEncoder()
    .username("user")
    .password("password")
    .roles("USER")
    .build()

     return InMemoryUserDetailsManager(user)
  }

We can now replace this in-memory user configuration with our new database-backed configuration. This ensures that Spring Security will use our UserDetailsService implementation to authenticate users against the database.

Great job👏! It's wonderful to see that the new user authentication system is working successfully with users stored in the database.

When I try to log in, I get a successful response:

In this section, we learned:

About UserDetails and UserDetailsService
How to implement them correctly
Why do we have all the methods implementations on UserDetails, even though we are not using them

Conclusions

sum up, we've accomplished the development of a user authentication system using Spring Security, integrating JWT to ensure secure and smooth user authorization. Despite the intricate nature of Spring Security, this tutorial has been designed to provide detailed explanations at each stage, helping to get a deeper comprehension of the implementation process.

For those looking to delve deeper into Spring Security, here are some suggested next steps:

Refer to the official Spring Security documentation for comprehensive insights into the framework.
Explore the topic of authorization with Marco Behler's article on authorization.
Gain a deeper understanding of the differences between ant matches and MVC matchers with Laurențiu Spilcă by watching this interesting video.
Check out Laurențiu Spilcă's book, Spring Security in Action, for an in-depth exploration of Spring Security concepts.
To enhance your understanding of JWT in Kotlin/Java, explore the JWT Library.

By using these guides and learning more about Spring Security, you'll be ready to make your applications solidly secure 🦸🏻‍♀️. If you ever have questions or need help, just ask. Have fun coding! 💻

Unleashing the Power of Spring Boot and Kotlin: Modernizing API Authorization Part II

Ruben Suet — Wed, 15 Nov 2023 08:43:59 +0000

In our previous discussion, we explored the interns of Spring Security, gaining insights into the orchestration of filters and the crucial function of the AuthenticationFilter in user authentication. Now, we switch our attention to a practical skill: the generation of Json web tokens. This skill will enable us to tap into the advantages of token-based authentication, enabling a process of user authentication smooth when it requests the different API endpoints from our app.

This article is your guide to mastering three key aspects in three parts:

Login via API: We'll kick things off by tackling the initial API login.
Implementing a JWT for Persistence: Learn how to keep your users authenticated via API using the shiny new JWT.
Connecting Database Users to Spring Security: Dive into the realm of syncing your database users seamlessly with the Spring Security system.

You might have observed that even after a successful login, the user is restricted from performing any subsequent actions. This limitation arises because we've configured all endpoints to require authentication, and with each HTTP request, the process starts anew, lacking persistence for the user. To address this, JSON web tokens(JWT) can be a valuable solution, allowing us to maintain user sessions for continued operations.

Our approach involves issuing a token with a validity period of up to 10 days. Beyond this duration, attempting further operations will result in a forbidden response, prompting the user to undergo the login process once again. To implement this, let's include the necessary dependencies in our pom.xml.

`pom.xml`

<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-jackson</artifactId>
  <version>0.12.3</version>
  <scope>runtime</scope>
</dependency>
<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-api</artifactId>
  <version>0.12.3</version>
</dependency>
<dependency>
  <groupId>io.jsonwebtoken</groupId>
  <artifactId>jjwt-impl</artifactId>
  <version>0.12.3</version>
  <scope>runtime</scope>
</dependency>

In contrast to the Spring Security package, the dependencies include a specified version. The version mentioned here corresponds to the one in use at the time of making this article. However, feel free to check for the latest versions on the Maven Repository website and opt for the most up-to-date version.

Esuring secure encryption, a JWT incorporates a signature that involves both the encryption algorithm and a secret key influencing the encoded token's outcome. The process involves three crucial steps:

JWT Creation upon User Login: Generate a JWT when a user successfully logs in.
JWT Verification on Each Endpoint Request: Validate the JWT on every endpoint request.
Token Validation with Correct Signature and Expiry Time: Validate the token by ensuring it has the correct signature and has not expired.

Create a JWT when a user is logged in

Let's initiate the process by creating a new file within the security package:

`JwtGenerator.kt`

@Component
class JwtGenerator() {

    fun makeToken(username: String): String {
        val secretWord = "This is my  secret word for Dev.to"
        val keySecretWord = Keys.hmacShaKeyFor(secretWord.toByteArray())

        return Jwts.builder()
            .subject(username)
            .issuedAt(Date())
            .expiration(Date(System.currentTimeMillis() + 864000000)) // Token for 10 days
            .signWith(keySecretWord)
            .compact()
    }
}

We designate this class within the Spring Boot context using the @Component annotation since it lacks Business Logic. While an @Service alternative is plausible, the choice is flexible based on your preference. Although the use of an object instead of a class is plausible, a future refactor will introduce the injection of the keySecretWord variable rather than hard-coding it here.

The line val keySecretWord = Keys.hmacShaKeyFor(secretWord.toByteArray()) is crucial for creating a SecretKey object. Here, the HMAC-SHA algorithm is employed, as detailed in the documentation. Should a different algorithm be more suitable for your needs, feel free to adjust it accordingly. The essential aspect is ensuring the presence of a SecretKey type.

It's important to note that the method Keys.hmacShaKeyFor(secretWord.toByteArray()) requires a ByteArray type as a parameter, necessitating the transformation from a String.

Transitioning to the second part of the code, its responsibility lies in generating a new JWT:

  return Jwts.builder()
            .subject(username)
            .issuedAt(Date())
            .expiration(Date(System.currentTimeMillis() + 864000000)) // Token for 10 days
            .signWith(keySecretWord)
            .compact()

The Jwts.builder() starts the creation of a new JWT based on the information specified in the subsequent commands.
The subject command defines the payload content; in this instance, we set the subject as the username, a parameter passed when calling the method.
The issuedAt command generates a timestamp indicating when the token is generated.
The expiration command determines when the generated token will expire. In our scenario, we set it to +10 days, but you can choose any time duration in milliseconds.
The signWith command configures a signature using our encrypted secret word, enhancing the security of the JWT.
The compact statement serves as the final directive to the builder, telling our builder that it's time to assemble the instance.

With this file, we can now integrate it into our login controller.

`LoginController.kt`

@RestController
class LoginController(
val authenticationManager: AuthenticationManager,
val jwtGenerator: JwtGenerator) {

  @PostMapping("/login")
  fun login(@RequestBody loginRequest: LoginRequest): ResponseEntity<Void> {

     val authenticationRequest = UsernamePasswordAuthenticationToken.unauthenticated(                
       loginRequest.username, 
       loginRequest.password
     )

     val authenticationResponse = authenticationManager.authenticate(authenticationRequest)

     val token = jwtGenerator.makeToken(loginRequest.username)

     return ResponseEntity.ok(LoginResponse(token))

  }

  data class LoginRequest(val username: String, val password: String)
  data class LoginResponse(val token: String)

}

The constructor injects the JwtGenerator.
A token is generated using jwtGenerator.makeToken(loginRequest.username) and stored in a variable.
If the token creation is successful, it returns the LoginResponse object.
The LoginResponse is a data class (data class LoginResponse(val token: String)) designed for returning data in JSON format. The response contains the generated token.

This is the outcome of the login process now:

Verify JWT

To make use of the received JWT, we need a mechanism to inform Spring Security that the token is verified. If the verification is successful, the user can then access the requested resource. Let's implement a token filter within the security package:

`JwtTokenFilter.kt`

@Component
class JwtTokenFilter() : OncePerRequestFilter() {


    override fun doFilterInternal(
        request: HttpServletRequest,
        response: HttpServletResponse,
        filterChain: FilterChain
    ) {
      val secretWord = "This is my  secret word for Dev.to"
      val keySecretWord = Keys.hmacShaKeyFor(secretWord.toByteArray())
      try {
        extractToken(request.getHeader("Authorization"))?.let { token ->
           Jwts.parser()
           .verifyWith(keySecretWord)
           .build()
           .parseSignedClaims(token)
           .payload
           .subject
           .let { user ->
             SecurityContextHolder.getContext().authentication =
                            UsernamePasswordAuthenticationToken(user, null, emptyList())
            }
          }
        } catch (e: SignatureException) {
            SecurityContextHolder.clearContext()
        }
        filterChain.doFilter(request, response)
    }

    private fun extractToken(authorizationHeaders: String?): String? {
        return authorizationHeaders?.takeIf { it.startsWith("Bearer ") }?.substring(7)
    }

This class inherits from OncePerRequestFilter, a subclass of GenericFilterBean. Understanding the difference between these two is crucial:

GenericFilterBean is a special class where you must implement the doFilterInternal function. The logic you put inside will be encapsulated and run arbitrarily through Spring Security filters. Spring Security determines when this logic runs in the filter chain but can apply it multiple times.
OncePerRequestFilter is similar to the above class but with a crucial distinction: the logic runs only once. It forces Spring Security to confirm that if the logic is validated, there is no need to revisit and re-check it.

The implementation convention for the doFilter method is as follows:

override fun doFilterInternal(
        request: HttpServletRequest,
        response: HttpServletResponse,
        filterChain: FilterChain
    ) {

Making sure that you include the parameters in this method is vital. At the end of our method, we execute filterChain.doFilter(request, response). This statement ensures that the filters from the filter chain continue to run. Forgetting this line may break the flow and result in unexpected behavior.

Regarding Keys.hmacShaKeyFor, it is not necessary to provide an additional explanation. Just remember that it must exactly match the value used as a String previously. We will refactor it later to centralize this information, but for now, we'll proceed with a small proof of concept and make adjustments afterwards.

 extractToken(request.getHeader("Authorization"))?.let { token ->
           Jwts.parser()
           .verifyWith(keySecretWord)
           .build()
           .parseSignedClaims(token)
           .payload
           .subject
           .let { user ->
             SecurityContextHolder.getContext().authentication =
                            UsernamePasswordAuthenticationToken(user, null, emptyList())
            }
          }
        } catch (e: SignatureException) {
            SecurityContextHolder.clearContext()
        }
        filterChain.doFilter(request, response)
    }

We extract the token based on the helper method mentioned at the end of the file. This small helper method takes the first 7 characters from the authentication in case it exists. Typically, for JWT authentication, a common convention is to add the prefix "Bearer" and then the token. You can use any prefix, but it's crucial to consider the character count for extracting the prefix and white space. In ThunderClient for VSCode, there's an option for "Bearer" token type authentication, allowing easy inclusion of the prefix.

If, for some reason, your API client lacks an authorization section, you can manually add it to the headers.

Once the token is extracted from "Bearer," we pass the value into a new context named token using the let command. The ? before ensures that we have a value or return null otherwise, preventing the execution of the following block context if no value is present.
The JWT parser is invoked to transform the encrypted JWT into a proper payload for reading. The same secretKeyword signature is used to apply the algorithm. It's crucial to use the same string; otherwise, the process will fail.
The token is built, and its signature is verified with parsedSignalClaims, where it checks the algorithm and secret word inside the token against our own signature (HMAC-SHA algorithm and the secret word).
We extract the payload (the content of the returned token, where the username was placed in the subject during token generation). The subject is extracted, holding the username.
In the following critical process, if we have a username, a new context with let is invoked to pass the username as a value. SecurityContextHolder is invoked manually. Remember, the SecurityContext holds all the critical information. We're manually stating that this token corresponds to an authenticated user. We save the authentication as a new UsernamePasswordAuthenticationToken object, holding our username. The three parameters passed are:
- Principal, which holds the username.
- Credentials, holding the password. As we do not store a password in our JWT, it's set as null.
- Authorities, representing the roles of the user. This is related to the authorization topic, which we do not address here. If needed, you could store the user's role in the payload and set it here. In our case, we pass an empty list because we treat all users on the website as the same type.

With this file, we can filter and check the provided token from the user, ensuring its validity based on our JWT signature, and set our user as authenticated. One part is missing: ensuring that our JWT filter is applied before the authentication filters like BasicAuthenticationFilter or UsernameAndPasswordFilter. Let's update our security filter chain method to instruct the framework to apply our custom filter before the authentication filters.

`SecurityConfig.kt`

@Configuration
class SecurityConfig {
  // Other methods....
   @Bean
   fun securityFilterChain(http: HttpSecurity, jwtTokenFilter: JwtTokenFilter): SecurityFilterChain {
      http {
        csrf { disable() }
        addFilterBefore<UsernamePasswordAuthenticationFilter>(jwtTokenFilter)
        authorizeHttpRequests {
           authorize("/login", permitAll)
           authorize(anyRequest, authenticated)

        }
      }
        return http.build()
  }
}

The JwtTokenFilter is injected, and the method addFilterBefore is specified. In our language, addFilterBefore<UsernamePasswordAuthenticationFilter>(jwtTokenFilter) indicates: Before the UserNamePasswordAuthenticationFilter, please apply the custom jwtTokenFilter. Now our filter placement is not arbitrary; we have deliberately decided where to position it. This ensures that an authenticated user is created before all the necessary checks are applied, facilitating the framework's operation and allowing us access to the endpoints.

Validate JWT

This is already looking good, but currently, only the signature is being checked. What if we also want to verify the expiration date? Same as before, the validation logic will be implemented in another file in the security package, where we set the same secret word and algorithm to transform it into a SecretKey and then validate.

`JwtTokenValidator.kt`

class JwtTokenValidator {
    fun validateToken(token: String) {
      val secretWord = "This is my  secret word for Dev.to"
      val keySecretWord = Keys.hmacShaKeyFor(secretWord.toByteArray())
        try {
          val jws: Jws<Claims> = Jwts.parser()
            .verifyWith(keySecretWord)  
            .build()
            .parseSignedClaims(token)      

          if (jws.payload.expiration.before(Date())) {
              throw RuntimeException("Token is expired")
          }

        } catch (e: SignatureException) {
            throw RuntimeException("Invalid Token Signature", e)
        } catch (e: Exception) {
            throw RuntimeException("Token Validation Failed", e)
        }
    }
}

In this case, I've chosen not to annotate it with @Component since I will only use it in the JwtTokenFilter, and I already have all the necessary information to make it work. Therefore, the Spring context is not needed to manage this file. Focusing on this snippet:

 val jws: Jws<Claims> = Jwts.parser()
            .verifyWith(keySecretWord)  
            .build()
            .parseSignedClaims(token)      

          if (jws.payload.expiration.before(Date())) {
              throw RuntimeException("Token is expired")
          }

As in the filter, it is parsed from what is received as a token into an object that can be processed. In this case, we check again the signature with verifyWith and parseSignedClaims. In reality, this step could be skipped since we are already checking it before in the filter, but I think it does not harm to check it out twice, and it's not computationally expensive if checked twice.

The interesting part is when we are extracting the expiration, and it is compared with a Date() that will return your current system time. If it's expired, then an exception is thrown. We can test this validation if we change the expiring date from our JWT when it's generated.

Let's add the validation file to our filter:

`JwtTokenFilter.kt`

class JwtTokenFilter() : OncePerRequestFilter() {

  private val tokenValidator = JwtTokenValidator()

 override fun doFilterInternal(
        request: HttpServletRequest,
        response: HttpServletResponse,
        filterChain: FilterChain
    ) {
        // Secret words variables...
        try {          
          extractToken(request.getHeader("Authorization"))?.let { token ->
                tokenValidator.validateToken(token)
                Jwts.parser()
                    .verifyWith(keySecretWord)
                // rest of the method...
        }
    }
}

Notice how I added tokenValidator as a property in the class, and then when the token is checked via let, before proceeding, we apply our validateToken by sending the token.

You can change your JWT generator milliseconds option to only last for 10 seconds; try to log in and check an endpoint constantly with the token for the following 10 seconds, and you will notice that eventually, it will return a 403 forbidden.

Refactoring the secret word

It is not ideal to have the same secret word defined and transformed into SecretKey up to three times. Let's add the word in our application.properties.

`application.properties`

jwt.secret-word=This is my  secret word for Dev.to

In our SecurityConfig file, we can retrieve it as a @Value and create a @Bean for it.

`SecurityConfig.kt`

@Configuration
class SecurityConfig {
    @Value("\${jwt.secret-word}")
    val secretWord: String? = null

    @Bean
    fun jwtSecretKeyword(): SecretKey = Keys.hmacShaKeyFor(secretWord?.toByteArray())

  // The other methods that we worked through this tutorial
}

@Value injects into secretWord the value of our application.properties. Since this is Kotlin, the $ has a special meaning, and we need to escape it to make it work for the value. Now it's only a matter of injecting it into the constructor of the generator and the filter:

`JwtGenerator.kt`

@Component
class JwtGenerator(private val jwtSecretKeyword: SecretKey) {
  fun makeToken(username: String): String {
     // I removed the secretWord 
     return Jwts.builder()
     // Methods from the builder
      .signWith(jwtSecretKeyword) // injected secret word
     // Rest of the method
  }
}

`JwtTokenFilter.kt`

@Component
class JwtTokenFilter(private val jwtSecretKeyword: SecretKey) : OncePerRequestFilter() {

    private val tokenValidator = JwtTokenValidator(jwtSecretKeyword) // I am sending the secret word from the constructor to the validator

  // change .verifyWith(keySecretWord) with .verifyWith(jwtSecretKeyword)

In our validator too:

`JwtTokenValidator.kt`

class JwtTokenValidator(private val jwtSecretKeyword: SecretKey) {
   // change .verifyWith(keySecretWord) with .verifyWith(jwtSecretKeyword)

}

This is why I wanted to go with a class since the beginning with this file. If we didn't have anything in the constructor, we could have an object instead of a class, which would have ensured that this would be a singleton in our app. However, since this will only be used in the TokenFilter and it will be already a bean singleton, our validator should be safe as well.

One last refactoring to apply: Our Controller is managing the login system from the previous section. We could move the authentication process to a service, and then our controller would only be able to receive the HTTP call and send the info to the different services that will manage the logic.

Let's create an AuthenticatorService in our security package:

`AuthenticatorService.kt`

@Service
class AuthenticatorService(val authenticationManager: AuthenticationManager) {
    fun authenticate(username: String, password: String) {
        val authenticationRequest =
            UsernamePasswordAuthenticationToken.unauthenticated(
                username, password
            )

        authenticationManager.authenticate(authenticationRequest)
    }
}

And our LoginController will look like this:

`LoginController.kt`

@RestController
class LoginController(
    val jwtGenerator: JwtGenerator,
    val authenticatorService: AuthenticatorService,
) {

    @PostMapping("/login")
    fun login(@RequestBody loginRequest: LoginRequest): ResponseEntity<LoginResponse> {
        authenticatorService.authenticate(loginRequest.username, loginRequest.password)

        val token = jwtGenerator.makeToken(loginRequest.username)

        return ResponseEntity.ok(LoginResponse(token))
    }
}

In this section, we learned:

Creating our own JWT when a user logs in
Know about how to add custom filters in the FilterChain and verify from there our JWT
Place our custom filter in a specific order
Validate our token to make sure that the signature and expiry date are still valid

Unleashing the Power of Spring Boot and Kotlin: Modernizing API Authorization Part I

Ruben Suet — Wed, 15 Nov 2023 08:43:15 +0000

So, you've decided to dive into the world of API authorization with Spring Boot and Kotlin. Exciting, right? Well, almost. As I went deeper into the docs and various tutorials, I stumbled upon a common frustration - outdated syntax everywhere!

Picture this: Most JWT methods are stuck in the past, and even some parts of the Spring Security package haven't received the memo on updates. Talk about a coding headache! Thankfully, a bit of Stack Overflow magic guided me to the elusive new syntax.

Now, why am I here writing this? Simple. I want to spare you the frustration and showcase the latest syntax. But hold on, it's not just about the code. I'll walk you through the flow, the gears behind the implementation, and the magic that makes it all tick.

This article is your guide to mastering three key aspects in three parts:

Login via API: We'll kick things off by tackling the initial API login.
Implementing a JWT for Persistence: Learn how to keep your users authenticated via API using the shiny new JWT.
Connecting Database Users to Spring Security: Dive into the realm of syncing your database users seamlessly with the Spring Security system.

Buckle up! We're about to make your Spring Boot and Kotlin journey smoother and more enjoyable. 🚀

Prerequisites

Before delving into the technical intricacies, let's establish some groundwork. This post assumes you've already set up a functioning Spring Boot application intricately tied to your database. If you're not there yet, don't fret. Check out this official Spring Docs tutorial for a comprehensive walkthrough on creating an application and establishing a connection with your preferred database. No need to stress about a User model at this point; we'll revisit that later.

In this discussion, I'll be working with Kotlin 1.9.20, Spring Boot 3.15, and Spring Security 6.15. My project aligns with Maven, but fear not, Gradle aficionados – adapting the steps to your build script is a breeze.

Now, let's dive into the essentials with a touch of seriousness.

Login via API

Your application is live, the database is connected, and your API endpoints are ready for action. Now, let's integrate Spring Security into your pom.xml.

`pom.xml`

<dependency>             
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-security</artifactId>
</dependency>

Upon starting your server and attempting to access an endpoint, a 403 forbidden response may halt your progress. This occurs because Spring Security defaults to requiring user authentication for all pages, restricting access to resources. Remember, Spring Security excels in both Authentication and Authorization, and today, we're focusing on the authentication aspect.

To enhance security, let's create a new package named security within your app. Most of our code will find its home there. Now, proceed to craft a new configuration file inside this dedicated package.

`SecurityConfig.xml`

@Configuration
class SecurityConfig {

    @Bean
    fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            authorizeHttpRequests {
                authorize(anyRequest, authenticated)
            }
            formLogin { }
            httpBasic { }
        }

        return http.build()
    }

    @Bean
    fun userDetailsService(): UserDetailsService {
        val user = User.withDefaultPasswordEncoder()
            .username("user")
            .password("password")
            .roles("USER")
            .build()

        return InMemoryUserDetailsManager(user)
    }

}

The code, sourced directly from the Spring security docs., might seem complex at first. Let's break it down:

We're establishing a @Configuration class with its own set of @Beans. If these concepts seem unfamiliar, refer to Gustavo Peiretti's detailed article for a clearer understanding.

Now, the crux of the matter— the securityFilterChain method. Spring Security operates on filters, each responsible for specific authentication and authorization tasks.

Remember, these filters manage authentication and authorization. We'll delve into some of them for the authorization process later on. A filter chain is distinct; by creating a method returning a SecurityFilterChain type, you open the door to customizing behaviors for these filters. The filter chain cleverly delegates customization, but maintaining order aligns with the real filters for optimal configuration.

@Bean
    fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            authorizeHttpRequests {
                authorize(anyRequest, authenticated)
            }
            formLogin { }
            httpBasic { }
        }

        return http.build()
    }

Having HttpSecurity in our grasp from the methods, we can start shaping our customizations.

Our first move is to employ authorizeHttpRequests. As the name implies, it's all about deciding what's available to both authenticated and non-authenticated users in our app. Notice that for anyRequest, we're declaring that we want the user to be authenticated.

The next player in the scene is formLogin. It signals our intention to use the default login form from Spring Security. However, hold your horses🐴—we'll remove this later since our goal is API-based authentication. On the other hand, httpBasic clarifies the authentication methods in play. It could be Form, Basic, or Digest. In a nutshell: Form is for HTML form information, Basic is for HTTP authentication, and Digest is an older method, not recommended anymore. Learn more here

Now, let's wire it all together and build our customized rules. Once processed, every rule will seamlessly attach to its designated parts in the different filters and work its magic.

If you're curious about where these rules go, here's a sneak peek for our small example:

1.The authorizeHttpRequests configuration governs access control and authorization. It typically aligns with the FilterSecurityInterceptor in the filter chain, enforcing access control rules.

2.The formLogin configuration is all about form-based authentication. It corresponds to filters like UsernamePasswordAuthenticationFilter and others in the authentication section of the filter chain. This filter handles the processing of login forms.

3.The httpBasic configuration is linked to HTTP Basic authentication. It usually syncs up with the BasicAuthenticationFilter in the filter chain, dealing with basic authentication requests.

An important note: Spring Security offers its DSL for Kotlin, enabling the bracketed syntax for each command. In Java, this would be something like:

http
  .authorizeHttpRequests((authorize) -> authorize
    .anyRequest().authenticated()
  )
  .httpBasic(Customizer.withDefaults())          
  .formLogin(Customizer.withDefaults());

Even though this is not related to Spring security, Learn more about Kotlin DSL here

Moving on to the next piece of config:

@Bean
  fun userDetailsService(): UserDetailsService {
    val user = User.withDefaultPasswordEncoder()
    .username("user")
    .password("password")
    .roles("USER")
    .build()

  return InMemoryUserDetailsManager(user)
}

This segment is a critical aspect of our app. Spring Security always verifies users and cross-checks their information through UserDetails. While we plan to implement our custom UserDetails and UserDetailsService down the road, let's first establish a solid proof of concept.

In this method, we're creating a new user with a username, an encoded password, and a role. This information is then used to construct the user, and we return an InMemoryUserDetailsManager. This manager crafts a user in memory for the app, allowing us to concentrate on refining our login system without being bogged down by database intricacies.

Later on, we'll seamlessly integrate our users from the database into the framework. But for now, this approach provides a pragmatic solution for our initial focus on the login system. 🚀

With our user created and the basic configuration in place, let's now enable a REST endpoint for the login process. We'll augment our config file with two additional methods:

@Configuration
class SecurityConfig {
  // Our user details and security filter chain methods
 @Bean
   funpasswordEncoder() : PasswordEncoder = BCryptPasswordEncoder()

@Bean
  fun authenticationManager(
    userDetailsService: UserDetailsService,
    passwordEncoder: PasswordEncoder): AuthenticationManager 
 {
    val authenticationProvider = DaoAuthenticationProvider() 

    authenticationProvider.
      setUserDetailsService(userDetailsService)      
    authenticationProvider.
      setPasswordEncoder(passwordEncoder)

    return ProviderManager(authenticationProvider)
  }
}

Let's break it down:

passwordEncoder()
Starting with the straightforward one: BCryptPasswordEncoder. This is one of the many options available for encrypting and decrypting passwords. By making it available as a bean, we ensure its accessibility across the platform.

authenticationManager()
Now, the AuthenticationManager interface takes center stage. It's where the real magic happens in our app. This interface is responsible for authenticating users, usually taking an Authentication object to determine whether the user attempting to access our app can log in. Upon successful login, it returns an Authentication object specifying the user's authority (or role).

Here's a closer look at what's going on:

We create a DaoAuthenticationProvider, an implementation of AuthenticationProvider. This configures our AuthenticationManager to understand how to process information and decide whether to grant authentication to the user attempting to log in.
We pass our custom UserDetailsService, complete with our in-memory user, and the encryption system we just created using BCrypt. To dive deeper into the behind-the-scenes mechanics, let's explore this visual aid:

This illustration sheds light on the intricate authentication process orchestrated by the AuthenticationManager. 🛡️ Nevertheless, let's break it down:

1.AuthenticationFilter Entry (Filter in the Chain): The user's authentication endeavor begins as they step into the AuthenticationFilter, one of the filters in the chain.

2.Token Generation (UsernamePasswordAuthenticationToken): A token is crafted at this stage. This token, known as UsernamePasswordAuthenticationToken, is initially unauthenticated. It serves as a precursor, guiding the AuthenticationManager on how to handle the incoming request.

3.AuthenticationManager Delegation: The AuthenticationManager takes center stage, determining the user's authentication status. This responsibility is delegated to the ProviderManager, which holds key information:

Provider: Specifies from where to fetch user information (UserDetails).
Password Encoder: Defines the encryption system for passwords.

4.DaoAuthenticationProvider Activation: The ProviderManager activates the DaoAuthenticationProvider, a critical cog in the authentication wheel.

5.Encryption System Configuration: The selected encryption system for passwords is set up.

6.UserDetailsService Interaction: The UserDetailsService, yet to be fully implemented, will retrieve information about users. Currently, our approach involves in-memory users.

7.UserDetails Lookup: The service seeks insights within UserDetails (to be implemented later), a Spring Security mechanism for managing user-related information.

8.User Model Creation: A preliminary user model is constructed, bridging the gap between our in-memory user configuration and the envisioned fully-fledged entity that will connect with our database (our Entity is yet to be implemented).

9.Backtracking Steps: The journey retraces its steps, reiterating through the authentication mechanisms.

10.Security Context Update: This crucial step updates the Security Context, the repository where all vital information from the filters is stored. It acts as the backbone of Spring Security, holding critical details about the user's authentication status.

Conclusion: The authentication process concludes, leaving the Security Context enriched with user-specific details, confirming their authenticated status. This context becomes the key concept of Spring Security, ensuring the seamless flow of authenticated interactions. 🔄🔐

Could you have ever imagined the amount of information embedded in this small @Configuration example? I certainly didn't. If you find yourself a bit disoriented, I suggest revisiting the presented diagram above with the provided example. Understanding the dynamics of the FilterChain and grasping the role of the AuthenticationFilter provides a clear idea of what lies ahead. Take your time to understand it and revisit it, if necessary.

Now, it's time to introduce an endpoint for the Login feature. In your app, you know the prime location for a new controller. For the purposes of this article, I'll place most components within the existing security package to keep them organized. 🗺️

`LoginController.kt`

@RestController
class LoginController(val authenticationManager: AuthenticationManager) {

  @PostMapping("/login")
  fun login(@RequestBody loginRequest: LoginRequest): ResponseEntity<Void> {

     val authenticationRequest = UsernamePasswordAuthenticationToken.unauthenticated(                
       loginRequest.username, 
       loginRequest.password
       return ResponseEntity.ok()
     )

     val authenticationResponse = authenticationManager.authenticate(authenticationRequest)

  }

  data class LoginRequest(val username: String, val password: String)
}

In this implementation, we introduce a simple DTO, LoginRequest, which encapsulates the username and password.

The login method begins by crafting the authentication token (authenticationRequest) of type UsernamePasswordAuthenticationToken. This token is then used to authenticate the user through the AuthenticationManager set up in the configuration file. As Spring Security navigates through the various filter chains, it addresses fundamental questions:

Does the user exist?
Are the credentials accurate?
Is the user permitted to access the targeted endpoint? (Authorization)
What roles does the authenticated user possess?

These inquiries represent just a fraction of the complexities that Spring Security adeptly manages on our behalf. At the culmination of this chain, armed with a wealth of information, the framework determines whether to authenticate the user and grant access to the endpoint. For our specific login scenario, where authorities are not pivotal, the outcome is binary:

Success: The application recognizes you as an authenticated user, resulting in a 200 OK response.
Failure: The application denies your login attempt, responding with a 403 Forbidden.

This is the elegance of the AuthenticationFilter 🙂, effortlessly orchestrating a multitude of tasks. While our SecurityFilterchain primarily concerns itself with authorization, the synergy between these components ensures a robust security framework.

@Bean
fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
    http {
        authorizeHttpRequests {
                  authorize(anyRequest, authenticated)
        }
        formLogin { }
        httpBasic { }
        }

    return http.build()
}

We are checking for every single endpoint and prooving that we are authenticated, including our /login endpoint. Let's modify this snippet that was a literal copy-paste from the Spring docs and adapt it a bit:

@Bean
fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
    http {
            csrf { disable() }
        authorizeHttpRequests {
                authorize("/login", permitAll)
                authorize(anyRequest, authenticated)
        }
        }

    return http.build()
}

In this refined configuration, we've removed the unnecessary formLogin and httpBasic configurations since our application exclusively provides REST endpoints, eliminating the need for HTML-based authentication. The csrf protection has been disabled, given the absence of HTML forms. While this decision should be approached cautiously, it aligns with the specific context of not providing HTML in this scenario. It's crucial to address CSRF concerns appropriately, and I strongly advise collaboration with the front-end team for a comprehensive solution.

The addition of authorize("/login", permitAll) ensures an open door for unauthenticated access to the login endpoint, catering to the specific requirements of a RESTful authentication flow. Always keep in mind that the order of authorizations matters, and the app processes them from top to bottom. The final rule, in this case, ensures that any unspecified request must be authenticated. Once you have run the app and sent a request with a username and password, you should receive a delightful 200 OK. 🚀

In this section, we learned about:

What is Spring Security and what does it do
What are Filters and what is the FilterChain in a Spring Security app
How to add our custom logic inside the FilterChainSecurity
How to add a user in memory viva UserDetails
How the AuthenticationFilter works, and how it works along with AuthenticationManager
The importance of Spring Security Context

If you're curious about the inner workings of Spring Security, I'll share a visual representation of the entire framework in action. Keep in mind that you don't need to familiarize yourself with every single filter and implementation. However, grasping the overall functioning of filters, especially in the context of our exploration with the AuthenticationFilter, provides valuable insights. This understanding guides you in navigating the filter chain and making targeted customizations for enhanced security.

Now, imagine the beauty of this illustration 🌹. The chain unfolds in a structured manner from top to bottom, showcasing the sequential delegation of implementations. This visual representation highlights the two primary domains that Spring Security effectively handles: Authorization and Authentication. It offers a comprehensive view that helps in understanding how filters are orchestrated and empowers you to make customizations across various segments of the filter chain.

Set up NextJs 9.4 with Prismic as Headless CMS

Ruben Suet — Mon, 25 May 2020 07:14:47 +0000

NextJs 9.4 ... When Tim introduced the new features of NextJs I understood from that moment on, this framework came to start a new era of server-side rendering. It came just on time as I was about to set up a new side project, and it's the perfect excuse to do some playgrounds with the new functionalities while doing so. Check out the new changes here.

One thing I noticed, were the vast amount of examples available. Great, I wanted to set up a page with Prismic, so I can just check the example and based on that move on. Well there's an example, and a bunch of boilerplate to look nice and complete. So it does its job, but I was looking only for the connection to Prismic, and that example was too complete for my learning purposes. Plus, where's the fun when everything is already set? Check out the example

Wait! I do not know your current knowledge of NextJs, or Prismic. So why am I showing you already the changelog from a framework that maybe you never worked on it? Let's move back 1 step back, so we can move 2 steps forward. In this tutorial I intend to briefly explain to you:

What is NextJs?
What is Prismic?
How do they work together?
Why is this combo good?

How do I intend to answer all these questions? Making a tutorial of how to set up a NextJs project, explaining what we are doing, and connecting it to Prismic. We'll be doing a blog

Set up a NextJs project
Prismic
Connecting NextJs with Prismic
Understanding NextJs and its pre-render
Dynamic routing
- Links in NextJs with dynamic routing
Where to go from now

⚠️ For this tutorial is necessary some knowledge in React and HTML

Set up a NextJs project

NextJs is a framework to do Server-side rendering in React applications. If you don't know what is Server-side rendering (from now on SSR), just check other pages from dev.to In the last 2 years, NextJs gained popularity, being one of the most solid solutions when you think in your app in SSR. So, let's start a new project:

npm init next-app

It will ask for the name of the project, and which template do you want. You can pick the default starter, since we are building everything from scratch.

Check the code and discover there's the following structure:

The pages folder is the most important folder. To get all the benefits from NextJs, you need to keep your pages under this folder. Notice that there's as well a sub-folder called api with a hello.js file. Go ahead and remove the folder and the file, we don't need them for the tutorial. Now, you can run the server:

npm run dev

You should see a page like the following picture:

Notice as well that a new hidden folder has been created as .next. This is internal from the framework and we shouldn't touch it.

If we analyze the code from pages/index.js we'll see a React component with some info. as well in the bottom some JSX. NextJs by default supports CSS modules, and support Sass. You can work with CSS in JS as well. For this tutorial we don't need any CSS at all, but I can refer you where to go once this tutorial is finished to learn more about it.

An important detail; do you see import * as React from 'react' ? The definition is implicit by NextJs. If you need to use explicitly the React library, you may need to import it (like a Fragment or one of the React hooks), otherwise, you can leave it as it is. Check what Tim said about it.

As well there's a Header internal component from NextJS. There are 4 in build components( and really important ones) out of the box:

In short words: Head is the component to place HTML tags in your head of the HTML document. But for this tutorial we don't need it either. Let's leave the document like the following snippet:

export default function Home() {
  return <></>
}

Prismic

Prismic is a headless CMS. In short words: You prepare your pages and your frontend receives a payload with the structure (JSON response) but it is up to you to do what you want with that info. What is the benefit of it? You can usually specify components in a headless CMS, and when you receive it in the payload, it tells you: Hey, here the content creator said it wants component X, so you can take the info from here, and delegate it into a React component, styled as you want.

It's perfect to separate content and code. Also great if the person who maintains the website does not know how to code. This gives them a solution and you just take care of processing the info.

Said that you need to open an account on Prismic. It gives great pricing offers, so there's a free plan for small projects. This is perfect for our tutorial, and even small apps like blogs/portfolios/newsletter.

Once you're logged in, create a new repository. Name it is as you wish (be creative! Otherwise just call it Blog 🤣). Enter into that repo afterwards.
On the left side you should see these 4 logos:

Let me quickly cover the first two:

Custom types(second logo): Here relies 'the skeleton' of our entries. You specify what do you want as a page. You can have single elements, or compose multiple elements interconnected with them. As well you can specify if this element is going to be unique on your website, or can be used multiple times. Think of it as the blueprint of a house. This section is for the dev.
Content(first logo): Here is mainly where you consume those custom types, those blueprints, and turn them into real pages. This section is for content creators/maintainers.

Let's go into the custom types and create a new one. We'll create the home of our blog. Since usually a homepage exists only once in your website, this is going to be a single type. Name it Blog home and give it the API id blog_home.

I'll briefly explain this page, but for a deep understanding I recommend check their documentation
On the left side, there are primitive elements that you can put on the main page. There's a drag'n drop concept. You can add it in the order you want and how you want it. The slice zone is a really interesting concept. Here you can create repeatable 'Components'. It will ask you for a name, and then you can drag and drop what you need to be there. Then this component will be consumed and added as many times as the editor needs. We won't use it for this tutorial, but keep in mind that this feature can give you a lot of power.Definitely try it out in some playgrounds once you are more confident with Prismic!

Check on the right side, there's a JSON builder as well, so you can edit it from there. To go aligned, I paste here my JSON and you can just add it in your example. You should have the same structure as in here:

{
  "Main" : {
    "headline" : {
      "type" : "StructuredText",
      "config" : {
        "single" : "heading1",
        "label" : "Headline",
        "placeholder" : "Main title..."
      }
    },
    "description" : {
      "type" : "StructuredText",
      "config" : {
        "multi" : "heading2",
        "label" : "Description",
        "placeholder" : "Sub-title..."
      }
    },
    "image" : {
      "type" : "Image",
      "config" : {
        "constraint" : {
          "width" : 140,
          "height" : 140
        },
        "thumbnails" : [ ],
        "label" : "Image"
      }
    }
  }
}

I added a Title, a subtitle, and an Image. Respectively, they are a head, a rich text and an image primitives from the visual builder.
You should see a page like this now:

I added the image field just for learning purposes, so we don't receive only formatted text. Don't forget to press the save button on the top right side of the page!!

Let's go ahead and build what we'll call a post entry. This time, the custom type can be used as many times as we want (we will have multiple post entries), so go ahead and create a Post custom type with API-ID as post. Here is the JSON:

{
  "Blog Post": {
    "uid": {
      "type": "UID",
      "config": {
        "label": "UID",
        "placeholder": "unique-identifier-for-blog-post-url"
      }
    },
    "title": {
      "type": "StructuredText",
      "config": {
        "single": "heading1",
        "label": "Title",
        "placeholder": "Blog Post Title..."
      }
    },
    "date": {
      "type": "Date",
      "config": {
        "label": "Date"
      }
    },
    "post_body": {
      "type": "StructuredText",
      "config": {
        "multi": "paragraph, preformatted, heading1, heading2, heading3, heading4, heading5, heading6, strong, em, hyperlink, image, embed, list-item, o-list-item, o-list-item",
        "label": "Post body",
        "placeholder": "Content of the blog post"
      }
    }
  }
}

We got it! Let's just go into the content tab on the left sidebar and create 1 Home Blog and 2 Posts. Feel free to add the content you want. The only thing you need to keep in mind is to save the content and publish it (top right side of the page). Until you don't see the bar in green, this content won't be public. This is how it should look once everything is saved and published:

Feel free to create 2 Post entries as well in the same way and save and publishing them.

Time for a break!🍵☕

Hey, a lot of new concepts and features. Why don't you refresh your mind for 5 minutes and go for a tea/coffee? A lot of new concepts and steps, you deserve it 💪

Once you are ready we'll get back into NextJs and apply all the connections to consume this new content.

Connecting NextJs with Prismic

Let's add 2 libraries to make the connection:

 npm I prismic-javascript prismic-reactjs

prismic-javascript will establish the connection, and prismic-reactjs will format the rich text we added.

Let's add a new file in the top level of our project called prismic-configuration.js

import Prismic from "prismic-javascript"

// Prismic API endpoint
export const apiEndpoint = process.env.PRISMIC_URL

// Access Token if the repository is not public
// Generate a token in your dashboard and configure it here if your repository is private
export const accessToken = process.env.PRISMIC_TOKEN

// Client method to query Prismic
export const client = Prismic.client(apiEndpoint, { accessToken })

Not a mystery, we establish the endpoint + token to connect to prismic and pass it into the library. From there we'll receive all the methods to keep working.

To retrieve the endpoint + token, we need to go in the settings sections (engine icon, bottom left of the page) from Prismic. Under the API & Settings tab, you will find easily the API Endpoint field, which holds our URL. Make sure it's under the JS option.

For the token, you will need to generate a new one on the same page. Just say it's private (only you query it). Once it's generated, it is the field that holds the Permanent access tokens section.
We got the info, so let's create a .env file at the top of our project:

PRISMIC_TOKEN= GENERATED_TOKEN
PRISMIC_URL= GENERATED_URL

Remember to add the .env file in the git ignore. With those steps, we are ready to consume our pages from prismic in the new NextJS Format.

Understanding NextJS and its pre-render

We set up a project, set up Prismic, and established connection. Our objective now is communicate this connection with NextJS. To make the call in the server-side we need to fetch data and pre-render it with getStaticProps. Let's go back into our initial index.js and extend it a little bit:

import Head from "next/head"
import Prismic from "prismic-javascript"
import { client } from "../prismic-configuration"

export default function Home() {
  return <></>
}

export async function getStaticProps() {
  const home = await client.getSingle("blog_home")
  const posts = await client.query(
    Prismic.Predicates.at("document.type", "post"),
    { orderings: "[my.post.date desc]" }
  )
  return {
    props: {
      home,
      posts,
    },
  }
}

Step by step:

We invoke getStaticProps to do the call in pre-render mode. This is how NextJS works to send data into the component then.
The client, from Prismic library, contains different helper methods. The getSingle means we want to retrieve a unique content (remember that we declared our home as a single type? Thanks to that we can retrieve it with this method). We pass as argument the UID we established for in the custom type.
We are doing another query into Prismic, but this time to ask about all custom types post, afterwards, we are ordering them. Learn about predicates in prismic. Notice how I needed the Prismic library to work with it.
It returns an object that contains the props, and inside the info that we want to send into the component. ⚠️ It is very important to return the props object, otherwise, it will fail.

At the end we can receive all this data in the component, and add it there:

import Link from "next/link";
import Prismic from "prismic-javascript";
import { RichText } from "prismic-reactjs";
import { client } from "../prismic-configuration";

export default function BlogHome(props) {
  return (
    <div>
      <img src={props.home.data.image.url} alt="avatar image" height="140px" />
      <h1>{RichText.asText(props.home.data.headline)}</h1>
      <p>{RichText.asText(props.home.data.description)}</p>

      <ul>
        {props.posts.results.map((post) => (
          <li key={post.uid}>
            {RichText.render(post.data.title)}
          </li>
        ))}
      </ul>
    </div>
  );
}

export async function getStaticProps() {...}

One thing that's worth to mention: Check out how is used now prismic-reactjs. You can convert rich text from Prismic into HTML with it. And its documentation is pretty quick and intuitive

Go ahead and see the home page:

npm run dev

Hey, we got it 🎉! Yes, I know..., the page looks quite horrible for now. But first things first, you learned this connection, now you can aply some CSS without mixing it to the basic structre.

Dynamic routing

We have a home page, but we want to have some pages. We would like to have one for every single post we have. To do that, we have to find a system that asks Prismic for the posts, checks if it exists, and if so, renders the content. NextJs has thought about this and provides a nice solution.

Let's create a folder inside pages called posts. Inside this folder, we'll create a [uid].js file. It should look like in the picture:

Why this weird brackets syntax? Because NextJs has established this way to know that this is going to be a page with a dynamic route. From now we can retrieve pages like:

http://localhost:3000/posts/:uid

We can retrieve the uid as a param and check in which page it belongs. Examples:
http://localhost:3000/posts/hello-world
http://localhost:3000/posts/hey-macarena
http://localhost:3000/posts/etc

Since we added this file under the folder posts, now every page is scoped under this name. An unrelated example would be: Image I create a file under pages/about/index.js will be found under /about route. Or if I create pages/services/our-services.js this page can be found under /services/our-services. In my opinion, it is an intuitive system and pretty straightforward to work.

Let's go back to our objective: Make this route dynamic. To do that we'll need two helper methods: 1- The getStaticProps that we already worked. 2- The new method getStaticPaths

Mainly getStaticPaths is the helper that builds all the pages in build time to match with the possible paths that the user can insert. Let's start with something easy:

import { client } from "../../prismic-configuration"
import Prismic from "prismic-javascript"

export async function getStaticPaths() {
  const { results } = await client.query(
    Prismic.Predicates.at("document.type", "post")
  )

  const paths = results.map(post => ({
    params: {
      uid: post.uid,
    },
  }))
  return {
    paths,
    fallback: false,
  }
}

We call Prismic and ask for all the posts. We've already seen this behavior with the previous page.
We map the results to have an array of object with a uid property. ⚠️ Two really important points - The array of objects always needs to be encapsulated under the params - The key of the params object, needs to match with the name of the file. In our case uid matches with [uid].js
We return the paths and the fallback as false.

I won't enter into a lot of details for fallback, just let you know that if it's false when no page is matched it will show a 404 page. Learn more about the fallback key.

Once more, we must return an array of objects that contains the params and the key inside the param is matching with the name of the file.

This helper won't work unless it goes together with getStaticProps, so let's add it:

export async function getStaticProps({ params }) {
  const { uid } = params
  const { data } = await client.getByUID("post", uid)
  return {
    props: { data },
  }
}

Now the function is expecting some parameters. Inside param we'll find what the user typed in the URL:

URL /posts/hello-world

Is transcribed into
{
    params: {
        uid: 'hello-world'
    }
}

Remember that what you called as the name of the file, is what you'll receive as param. In our case uid.

We ask to Prismic, with the helper getByUID to retrieve what the user adds in the URL. It must match with the uid value you added when you created a content in Prismic that is type Post. Otherwise, you won't be able to retrieve the content.

Once we got the page, we just return it in the props for the component. And now we can create a component that just inserts the info. So the whole file can look like this:

import { client } from "../../prismic-configuration"
import { RichText } from "prismic-reactjs"
import Prismic from "prismic-javascript"

export default function Post({ data }) {
  return (
    <React.Fragment>
      <article>
        <header>{RichText.asText(data.title)}</header>
        <main>{RichText.asText(data.post_body)}</main>
      </article>
    </React.Fragment>
  )
}

export async function getStaticProps({ params }) {
  const { uid } = params
  const { data } = await client.getByUID("post", uid)
  return {
    props: { data },
  }
}

export async function getStaticPaths() {
  const { results } = await client.query(
    Prismic.Predicates.at("document.type", "post")
  )

  const paths = results.map(post => ({
    params: {
      uid: post.uid,
    },
  }))
  return {
    paths,
    fallback: false,
  }
}

Check-in your app that enter into http://localhost:3000/posts/uid-of-your-post, and see the result. We did a great job here 👏 There's one last detail we forgot: How to link the home page with a post.

Links in NextJs with dynamic routing

Going back into our index.js. We find a list with all posts:

//Imports

export default function BlogHome(props) {
  return (
  ...
     {props.posts.results.map((post) => (
       <li key={post.uid}>
           {RichText.render(post.data.title)}
       </li>
     ))}
  ...
  );
}

export async function getStaticProps() {...}

To link them, we can use the in-build component Link from NextJs. Let's add it and explain what's going on:

// Other Imports
import Link from "next/link";

export default function BlogHome(props) {
  return (
  ...
       <li key={post.uid}>
           <Link href="posts/[id]" as={`/posts/${post.uid}`}>
              <a>{RichText.render(post.data.title)} </a>
            </Link
       </li>
     ))}
  ...
  );
}

export async function getStaticProps() {...}

The Link component needs an href prop, and this href needs to point into the path we specified in pages. Since it's dynamic, it goes under the brackets convention.
as is then to transform the path dynamically, based on the info we received from the list of posts.
For SEO reasons, you should wrap it with an <a> HTML tag. Then it can be properly read by BOTS.

Phewwww, so we got it! We created a new NextJS project from scratch, understood how it works, connected with Prismic, and consumed it. I hope this helped you to understand the basics of NextJS, and have the first contact with Prismic as headless CMS.

If you would like to compare your work with this tutorial, check the final result I wrote

Where to go from now

Now, we got the basics of the framework. If you would like to learn more about it, I strongly recommend do their tutorial. You will see some concepts as we saw here, but they are explaining as well what is static generator vs SSR, or which options do you have to apply some styles in your project, etc.

If you don't want to do another tutorial, I recommend jumping directly into their documentation. We covered the basics and from here you can start to develop with NextJs as well.

The last step would be to check Prismic documentation in detail to get all the benefits they can provide to you. There's even a CLI tool from Prismic for creating a new repository + all the custom types from the terminal. In my case I wanted to show you step by step how to do it, and that's why we didn't cover it with this tool.

I wish you the best in this journey of SSR. If you want to share feedback, experience, or just explain some code battles, you can find me on twitter 😊

The real power of the generics in Typescript

Ruben Suet — Sun, 10 May 2020 08:16:41 +0000

In Typescript, generics are often present in our code. However, at least in my case, it's because I consume them instead of declare them, but there's much more to do with it. Based on a real example, I would like to explain you why generics can be so powerful ⚔.

Generics: A major part of software engineering is building components that not only have well-defined and consistent APIs, but are also reusable. Components that are capable of working on the data of today as well as the data of tomorrow will give you the most flexible capabilities for building up large software systems. typescript offical repo

The theory from the official typescript page is clear, but what does that mean when it's in practice? Let's check a real example.

Google Analytics real case

Most of the professional environments, they are using analytics. They could have their own solution, or re-use a general solution as Google analytics or Adobe analytics, etc. In my current job, we are using Google Analytics. Our goal, mainly, is to track views and clicks on our components. Every component has it's own format to track in the body, so it needs to be different for everyone. It could easily applied that everyone has its own type definition explaining what do you expect at the moment that you create the object of tracking.

However, it was intended to create a general structure for them, a 'contract' specifying that always that a components wants to track, needs to fulfill some general spots that are shared between all components. Here's the picture:

export const getEvent = ({ event, category, action, label, body }) => ({
  area: MY_AREA, // In which page you are
  event, // A click or a view event
  scope: "ecommerce",
  currencyCode: "EUR",
  eventInfo: {
    category: `Enhanced Ecommerce | ${category}`,
    action, // Again, a click or a view
    label,
  },
  ...body,
})

Mainly this object generated is shared between all components. Having this component, we can ensure that all tracking will always take care to have a proper format to be sent into analytics, so no need to repeate the same structure for every component, and more over open the risk of more bugs.

This is how it looks my type for that:

type TrackEvent = {
  event: string
  category: string
  action: 'Click' | 'View' | 'Slide'
  label: string
  body: ??????
}

How can I know the type of body? This is the part that will be re-used for every component, but on the same time it's always different. So here is the power of generics

type TrackEvent<T> = {
  event: string
  category: string
  action: "Click" | "View" | "Slide"
  label: string
  body: T
}

From now on, TrackEvent accepts one parameter, and this parameter is passed to be in the body. Examples:

const myEvent: TrackEvent<string> = { body: "a string for the generic" }
const myEvent: TrackEvent<number> = { body: 22222 }
const myEvent: TrackEvent<string[]> = { body: ["hey", "ho"] }

Obviously these examples would complain cause you are missing the other types(event, category, etc..), but I just wanted to show how is used without any other context, so it's simple and straightforward.

From now, I am missing one piece of the puzzle: This type is used in a function, not in a new variable:

export const getEvent = <T>({ event, category, action, label, body }: TrackEvent<T>) => ({
  area: GENERATOR_META,
  event,
  scope: 'ecommerce',
  currencyCode: 'EUR',
  eventInfo: {
    category: `Enhanced Ecommerce | ${category}`,
    action,
    label,
    variableUsage1: undefined,
    variableUsage2: undefined,
  },
  ...body,
})
// Or if you prefer
export function getEvent <T>({ event, category, action, label, body }: TrackEvent<T>) {

What is going on here? From now on, the function is expecting one Generic( The first T after the variable declaration), and in the TrackEvent we pass this generic. Typescript is really clever, and know that this generic is associated into the body, so it will infer automatically for you.

let body = "hello"
getEvent({ event, category, action, label, body }) // Will automatically infer as String

body = {
  track: "hello",
}
getEvent({ event, category, action, label, body }) // Will automatically infer as { track: string}

// You Can force as well the type
getEvent<string>({ event, category, action, label, body }) // This enforce the body to be a string

As you can see, we found a way to declare the type of body, even not kowing what is its structure. In my opinion, Typescript does really good its job: automatic infer types. So I believe in it and I don't usually force the type when I invoke the function. However, if you need an extra layer of restriction, or a huge amount of people are often working in that file, it could help. But as I previously said, I support the idea of not explicitly saying which type do you need when the functions is invoked.

I hope this post helps you to understand a bit more about generics, and that we can do more than just consume them. Go ahead, and use the power of TS ⚔️⚔️⚔️⚔️🔥🔥🔥🔥

See the original post at my blog SuetBabySuet

TIP - Make your font responsive without media-queries Part II

Ruben Suet — Sat, 02 May 2020 11:21:55 +0000

After released the Tip to make your font responsive without media-queries, I was talking with my good friend @tonyioi, and he said: - Rubèn, I liked your post. It came into the right moment to apply it to my aside project thunderhub. But, What if the user has a huge wide-screen? or what about 4k? Isn't that to be then too big for the automatic responsive font?

He got a point there, my solution is scaling based on the screen, but I never defined a maximum, or minimum. And here's the second part of the TIP, to show you how to apply boundaries on the previous solution.

Let's catch again the previous snippet:

.my-title {
  font-size: calc(1.8rem + 1vw);
}

Quick reminder: The 1.8rem is just a number I came up, you can introduce any number that you like here.

What happens if you got a 3840 × 2160 resolution screen? 1vw will be 38.40 px, and with the addition of 1.8rem(based on 16px as font-based it turns as 28.8px) then we have a responsive font that is 67.2px 😂😅.

Min() and Max()

CSS math functions to the rescue! These 2 methods support almost all browsers (I am sorry IE). What do they do?

The min() CSS function lets you set the smallest (most negative) value from a list of comma-separated expressions as the value of a CSS property value - MDN docs

As example, if I do min(20px, 1em, 10vw). What will happen is that I will always take the smaller number based on the metrics I added. In my example, I went for 20px, 1em, and 10vw. But you can add as many options as you want. See it as an array of values to measure, it will always return the lowest number. So if 1em means 16px, based on the properties from my parent element, then 1 em will be taken over 20px. If 10vw (10% of the screen) is translated into less than 20px and 1 em, then that will be taken. For my example, I can do:

.my-title {
  font-size: min(calc(1.8rem + 1vw), 40px);
}

Now, if my calculation overpasses at some point the 40px, the min value will be 40 itself, and is the one to show.
Check it out in this super simple code-sandbox

For max() is the same but taking the largest number in the array. So with max, I can specify, at least, a minimum value to show:

.my-title {
  font-size: min(max(30px, calc(1.8rem + 1vw)), 40px);
}

So the max is taking the max between 30 and the automatically computed value (I am making sure that at least it will be always 30), and then with the min, I am taking care that the value has to be always under the 40px, since we always want the minimum there.

Cheatsheet:

.my-title {
  font-size: min(max(minValue, DesiredValue), MaxValue);
}

And with this trick, I hope you hate a bit less CSS and you start to like it a bit more 🥰.

Clamp()

Clamp function is exactly the combination of min() and max() into a single function, instead of wrapping 2 together. So our previous example becomes as:

.my-title {
  font-size: clamp(30px, calc(1.8rem + 1vw), 40px);
}

Much cleaner than before. The unique downside is that this method is pretty new for most of the browsers, and doesn't provide so much compatibility. I am pretty sure this is going to be standard in a while, but for now, in my opinion, it's safer the min() max() combination.

Let me know in my twitter if you are enjoying this series of TIPS, so I can know if I should keep doing it or focus more on a full article approach.

Thanks!

See the original post at my blog suetBabySuet

TIP - Make your font responsive without media-queries

Ruben Suet — Sat, 02 May 2020 11:17:32 +0000

Here's the point: Everytime that the browser can do a job for you, let the browser do it. Our goal, when we code to CSS is to guide this browser to do its best job. Take as example why people are trying to advocate for em over px.

This is the same scenario for media-queries: Our main mistake, is to create media-queries for everything in order to be "mobile first", but what we do is just re-creating several times a job that the browser could do easily with proper guidance.

Make your font responsive

How many times you saw something like

.my-title {
  font-size: 32px;

  @media (min-width: 752px) {
    font-size: 36px;
  }

  @media (min-width: 1232px) {
    font-size: 40px;
  }
}

3 definitions for a single rule. Imagine how can it be when there are 20 CSS properties defined here, trying to manage them in mobile first principle. That's why we need the media-queries, just for the necessary, and the rest just help the browser.

Here's my proposal:

.my-title {
  font-size: calc(1.8rem + 1vw);
}

Step by step:

The calc() function performs a calculation to be used as the property value. Via W3Schools
The vw holds for view-width. Relative to 1% of the width of the viewport. Via W3Schools

The vw is the magic sentence. It can hold for vw(view-width) or vh(view-height). Mainly it takes a 1% of your screen. So if your screen is 320px => 1vw = 3.2px If your screen is 752px => 1vw = 7.52px and if you have 1232px => 1vw = 12.32px. So there's a way that the browser can know dynamically the width of your screen, and we don't have to take care.

With the concept of vw now we combine it with calc. Assuming your font-base is 16px (the default unless you change it), that means:

Font-base = 1 rem   //Formula
font-base as 16px = 1 rem (16px) //Example
2 rem = 32px (2 times font base) //Example

1.8 rem holds for 28.8px. The rest I fill it dynamically with the dynamic with from vw

320px screen
- 1.8 rem + 1vw = 28.8 + 3.2 = 32px

752px screen
- 1.8 rem + 1vw = 28.8 + 7.52 = 36,32px

1252px screen
- 1.8 rem + 1vw = 28.8 + 12.52 = 41.32px

And with that, you got a responsive font. Probably you noticed the result of these numbers are not matching with the original 32, 36 and 40 we saw in the media-query. That's correct, probably you can play even more with the precision of the rem + vw combination, but in my opinion, is a small downside that I prefer to take instead of manually calculating the font-size with the queries. At the end we talk about .32px difference on Tablet and 1.32px on Desktop, the impact is minium compared with the benefit of good CSS code + good job for your browser. This solution is compatible for all browsers, included IE11.

I hope this can help you as much it helps me when I develop CSS. It really simplifies the idea and small tips like this are really changing the mindset of CSS to make it more interesting.

See the original post at my blog suetBabySuet

React Composition

Ruben Suet — Sat, 02 May 2020 11:02:30 +0000

In a previous post, I talked about React Context, a native alternative to sharing state like Redux or Mobx, or just to avoiding prop drilling. These other state sharing solutions imply time and effort to set-up and wire the state with your components. On the other hand with prop drilling you get a quick and straightforward solution without setting anything up. And together with this comes a simple, effective, and somehow not known pattern for it: React composition.

This posts motivation comes from a tweet from @mjackson which received many comments giving counter arguments to his idea. In response he decided to do a very nice explicative video about react composition which I recommended you watch as well. Now my intention with this post is to aggregate to these concepts exposed previosuly by mjackson without losing the initial reference. So let's continue on.

What is React Composition

React composition is one of the most basic techniques that we learn when we are working with react. It is mainly the children keyword. This example (for learning purposes) illustrates this pattern.

import * as React from 'react'

function DisplayCounter ({ children }) {
    return (
        <React.Fragment>
            <h1> My own counter </h1>
            <strong> Press the button and see the counter in action </strong>
            { children }
        </React.Fragment>
    )
}

function Counter () {
    const [counter, setCounter] = React.useState(0)
    const increase = setCounter(prevCounter => prevCounter +1)

    return (
    <React.Fragment>
        <DisplayCounter>
            <p> You have pressed { counter } times </p>
        </DisplayCounter>
        <button onClick={increase}> Increase! </button>
    </React.Fragment>
    )
}

I could have passed the counter prop into DisplayCounter and would have had no necessity to nest children here but imagine you now have a flow like this:

Counter (state is set) => anotherComponent => ... => displayCounter (consume states).
As you can see, you are now sending the prop through 2 or more components. It can easily be nested but now all of them have a strong dependency on that prop that they don't even use and are just passing it into the next component.
You could set up a React Context (or any state management library) but this solution is straightforward and gives me the benefit I was looking for.

Some real example

A header is often a component we can find in many web apps.

I need to pass User info into 2 places: The avatar itself, and the settings dropdown.Imagine we got this Tree component

The Header component is taking care to receive user info, and it spreads through the rest of the tree components.

In the classic approach, It would look something like:

import * as React from 'react'
import { fetchUser } from './someUtilsLibThatFetchesTheUser'
function Header () {
    const [user, setUser] = React.useState(undefined)
    React.useEffect(()=> {
        setUser(fetchUser())
    },[])
    return(
        <React.Fragment>
            <Avatar user={user} />
            <Menu user={user} >
        </React.Fragment>
    )
}

Not really nice to see so many user keywords. Moreover, if you make it with Typescript, you need multiple type definitions for that user object.

The idea here is to avoid prop drilling and make it easy.

import * as React from 'react'
import { fetchUser } from './someUtilsLibThatFetchUser'
function Header () {
    const [user, setUser] = React.useState(undefined)
    React.useEffect(()=> {
        setUser(fetchUser())
    },[])
    return(
        <React.Fragment>
            <Avatar>
                <img src={user.avatar} alt={user.username}>
            </Avatar>
            <Menu>
                { user ? <UserInfo user={user} /> : <LogIn/>
            </Menu>
        </React.Fragment>
    )
}

I am still sending one prop of the user, but now it's a single prop. Before probably would have been

The Menu, without composition, would originaly be:

import * as React from 'react'

function Menu ({ user }) {
    return (
        <React.Fragment>
            { user ? <UserInfo user={user} /> : <LogIn />
            <Settings/>
        </React.Fragment>
    )
}

Why, if the Menu does not need anything from the user, does it still need to receive it and pass it into another component?

With Composition, the Menu would like this:

import * as React from 'react'

function Menu ({ children }) {
    return (
        <React.Fragment>
            {children}
            <Settings/>
        </React.Fragment>
    )
}

Here relies the power, the previous snippet you could like it more or less (No entendi esta primera oración :S). Depending on your situation you could need React Context or maybe even a more complex library, but sometimes only with Composition could do. This Menu snippet, shows us that the component doesn't need to know about the user object, it's not coupled at all. Children is as well a really powerful technique for Compound components, which I will explain in another post.

So a few more words about it: notice how we passed from sending the User into the Menu component, and from the Menu into the UserInfo component, to avoiding this 'proxy' and just passing the info and delegating it to the parent component, the Header.
For the Avatar, let's assume the component was just some stylings and was waiting for the image. No need to show some snippet there :)

Conclusion

In my opinion, React Composition is a great tool that can greatly help at the moment of developing. (React docs are encouraging you to use it). If what you put as children is not really huge, Composition is the best technique. Otherwise, if you're children take like 200 lines of code, I would consider another technique like Context. At the end it is just another card in your hand you must learn when it's best to play at a specific moment.

References for this post

See the original post at my blog suetBabySuet

My experience with IntersectionObserver, scroll snap and React

Ruben Suet — Sat, 02 May 2020 11:00:36 +0000

It fascinates me how powerful but also how fragile JavaScript is. Until around 2010, no one would ever describe himself as a JS developer. Now-a-days thanks to node, the game changed and JS is one of the most used languages with every new iteration from TC39 making it stronger. To make it even more attractive, I think it's the only language that contains so many libraries/frameworks to work with it. Angular, Vue, React, Svelte, good old Jquery, Ember, Meteor, Stimulus, and so on... It's crazy.

And what do we do? We work with one of these libraries that makes our work easier and more productive, right? We became experts in that framework but forgot the initial abstraction, how Vanilla JS is handling everything behind the scenes. Today it's easier than ever to just download packages that do precisely what we are looking for, but we are not able to understand the non fancy code, the one coming from Vanilla JS.

And here comes the motivation behind my post: I want to talk about the Intersection Observer API. Going first through some pure JS examples, and how I later moved this code into a react environment. My intention is to explain my experience rather than have perfect code, so you might find some code that can be refactored along the way. Feel free to DM me @RubenSuet and I can double-check it 😊.

The use case

To understand why I need to play with some CSS rules or JS API, I need to explain what my issue was and how I started to tackle it. Currently I am a F.E dev in an E-commerce in the EU and like all of the e-shops in the world, the homepage consists mainly of getting the attention of the user, showing some products (maybe personalized, maybe not), and adding hot deals to make even more attractive the idea of buying some product.

And within all these deals and promotions, how can I display a big amount of products without overwhelming the user? With Carousels. They are ugly and are low performant but the user has control. If he wants to see more products he can. We are not forcing him to see all of them, just some of them, and it's up to them to keep clicking and interacting with the carousel to see more. On top of that, we have server-side rendering which means that the only way to make proper responsive pages are with pure CSS or guessing some User-Agent (this last one is pretty dangerous because you can never know which resolution is set).

And to top it all of, on mobile, there's one carousel that doesn't look at all like the one for Desktop. At this point you're guessing right: We are rendering multiple carousels for specific devices ( Sigh, I know. We are working on improving this which is also the reason why I am writing here: to share my progress). So, what can I do to perform better?

Some research

Let's check some E-commerce/marketplaces to see how they handle it. I did some research on several websites, but I would like to highlight 2 specific websites: Amazon and Zalando. Both have the same use case. You enter the website and they have something that looks like a carousel to show the products/categories. But it's not.

Notice how they are working with a simple list and are achieving a perfect "Carousel". The user is not even noticing it and the performance is just great. So how do they do it? Checking a bit the code, in the ul element I found the following:

element.style {
1.  scroll-padding-left: 672px;
2.  scroll-behavior: smooth;
3.  scroll-snap-type: x mandatory;
}

AHA! I had heard about this but never needed to work with it. This is what is called snap-scroll. It lets you create the effect of scrolling where you can position the scroll in specific alignment from the item, making the effect of the carousel. Please check as a reference this article from Max Kohler and this other article from Robert Flack and Majid Valipour.

So I presented this articule to my team seeing if we could try to do something like the examples shown above. And then... my dreams were gone. The analytics person from my team explained to me that it's not possible to track which elements are visible at specific moments and to be honest, I hated that idea, but he had a point.

How can I make it possible... Before continuing I decided to procrastinate for a bit on twitter when suddently I saw that @meduzen had posted exactly what I was looking for. He played with the Intersection observer to make sure that when an element is visible, it toggles a class and does a CSS animation. That's perfect. If I can toggle a class, I can for sure trigger a callback and make the analytics work, can't I?

More research on the internet showed me how to use the Intersection Observer (I'll post all my references at the end of this post), but none of them were tackling it in React. The only thing I found was an npm package, but this was exactly the intro of my post and before I use a solution that is already built, I wanted to understand the real abstraction and how it works. So I wanted to do it by myself, without dependencies to other libraries that do all the magic without you knowing what is going on.

Building my component with scroll-snap and Intersection Observer

First I'll show what I built and then I'll break it into smaller pieces. Here's a picture showing what I want to accomplish:

So, I have some sections, and when I am scrolling, I want to console log in which section I am at that specific moment. Here is my pure react component to achieve it:

//CarouselScroller.tsx
import  *  as  React  from  "react";
import  {  Section,  LightSection,  Container  }  from  "./CarouselScroller.styled";
const  CarouselScroller:  React.FC<{}>  =  ()  =>  {
    return  (
    <Container>
        <Section  color="#134611">
            Section 1
        </Section>
        <Section color="#3E8914">
            Section 2
        </Section>
        <Section color="#3DA35D">
            Section 3
        </Section>
        <LightSection color="#96E072">
            Section 4
        </LightSection>
        <LightSection color="#E8FCCF">
            Section 5
        </LightSection>
    </Container>
    <button  onClick={() =>  setCount(count + 1)}> Re-render</button>
    );
};

CarouselScroller.displayName  =  "CarouselScroller";
export  default  CarouselScroller;

I used styled components and made the <Container> the <Section> and the <LightSection>

// CarouselScrollect.tyled.ts
import  styled  from  "styled-components";

const  Container  =  styled.div`
`;

const  Section  =  styled.div<{ color:  string  }>`
    background:  ${props  =>  props.color};
    min-width:  70vw;
    height:  30vh;
    color:  white;
    display:  flex;
    align-items:  center;
    justify-content:  center;
    font-size:  28px;
`;

const  LightSection  =  styled(Section)`
    color:  #1f2d3d;
`;

export  {  Container,  Section,  LightSection  };

With these 2 files. I got exactly what you saw in the previous gif. However, it is still lacking the scroll snap. Let's add it

// CarouselScrollect.tyled.ts
import  styled  from  "styled-components";

const  Container  =  styled.div`
    scroll-snap-type:  x  proximity;
    display:  flex;
    overflow-x:  scroll;
`;

const  Section  =  styled.div<{ color:  string  }>`
    scroll-snap-align:  center;
// Other properties non related with scroll-snap
`;

scroll-snap-type: You need to specify how it locks into the viewport when it scrolls. That usually is the parent component that wraps the children to make the effect and is the first rule you need to specify to use the snap module. Usually, you can specify the axis x or y and choose as a second option which kind of 'lock' you want to use. There are 3 properties:
- none: You scroll normally, it doesn't force the scroll to anchor specifically at some point of the element
- proximity: When scrolling, between 2 elements it can force to anchor into one specific element.
- mandatory: The most strict option. It forces always to anchor the element where you align (is the option that the children have. We'll discuss it in a moment. I like this option if you want to do the effect of parallax or close it as a carousel.
Scroll-snap-align: Where do you want to align the item when it locks the scroller. The image from Robert Flack and Majid Valipour explains well this concept. I upload it here, but please remember this picture belongs to them ( and therefore they deserve to be referenced)

I will provide a sandbox link with the working project, feel free to do some playgrounds with the options. In the end, a picture is worth a thousand words.

Time to play with Intersection observer. Some Vanilla JS to make it work before we go. This is how it looks:

let observer = new IntersectionObserver(callback, options)

Check out we need a callback and options. Let's start with the last one since it's the easier one:

let options = {
    root: null // relative to document viewport
    rootMargin: '0px'// margin around root. Values are similar to CSS property. Unitless values not allowed
    threshold: 1.0 // visible amount of item shown concerning root
}

I tried to explain in the code itself what every option does but mainly you can specify another root ( like #gallery), the rootMargin if it needs a margin to start with and last (and I would say the most important one) but not least the threshold. How much of the item needs to be shown to trigger your callback with values from 0 (hidden) to 1 (fully shown). In my case it needs to be fully visible.

Let's check the callback

let callback = (entries, observer) {
    for(let entry of entries) {
        if (entry.intersectionRatio  >=  1) {
            console.log('I am visible!')
        }
    }
}

Please, note this is a simplified version just for learning purposes. You can fulfill it with any logic you want.

entries are going to be an array of IntersectionObserverEntry(thanks TS to help to put a name on this). And that's when I iterate it, you have the property intersectionRatio which is the one that determines if it's visible or not ( again, the value goes from 0 to 1).

Connecting the options and the callback you can notice that we specified a threshold of 1 and we check in the callback if this true, and if it is, then we do log it.

If you want to know more about IntersectionObserver check out the MDN docs. Apart from triggers for when elements are visible, IntersectionObserver lets you do lazy loading, infinite scrolling fetching new data, between others. Mainly it reacts when an element is in focus of the user. Cool API to be honest and I am not sure how I went so far without having the necessity to work with it.

At the end you can observer elements like

const images = document.querySelector("img")
for(let image of images) {
    observer.observe(image)
}

In this example, the observer reacts for all images in your document and does whatever you need to do.

Going back into the react component. Let's make it step by step:

const  CarouselScroller:  React.FC<{}>  =  ()  =>  {
    const  refs  =  React.useRef<HTMLDivElement[]>([]);
    const  observer  =  React.useRef<IntersectionObserver>(null);
    const  addNode  = (node:  HTMLDivElement)  =>  refs.current.push(node);

    React.useEffect(()  =>  {
        if  (observer.current)  observer.current.disconnect();

        observer.current  =  new  IntersectionObserver(handler,  options);
        for  (const  node  of  refs.current)  {
            observer.current.observe(node);
        }
        return  ()  =>  observer.current.disconnect();
    },  []);

    return  (
        <Container>
            <Section  ref={addNode} color="#134611">
                Section 1
            </Section>
            <Section  ref={addNode} color="#3E8914">
                Section 2
            </Section>
            <Section  ref={addNode} color="#3DA35D">
                Section 3
            </Section>
            <LightSection  ref={addNode} color="#96E072">
                Section 4
            </LightSection>
            <LightSection  ref={addNode} color="#E8FCCF">
                Section 5
            </LightSection>
            </Container>
    );
};

Step by step:

    const  refs  =  React.useRef<HTMLDivElement[]>([]);
    const  observer  =  React.useRef<IntersectionObserver>(null);
    const  addNode  = (node:  HTMLDivElement)  =>  refs.current.push(node);

Notice that I made it in TS (If you feel uncomfortable, just remove the <>). So first I create an array of refs. Here I want to store the html elements to observe afterwards. Then I create another ref for the observer. Without refs, a new IntersectionObserver would be created for every re-render, and I don't want that. At the end a quick method to push the refs into the array I declared before. And this is how I store them in the return method:

<Section  ref={addNode} color="#134611">
    Section 1
</Section>

So with that, I can have all my refs stored. Now let's check my useEffect.

React.useEffect(()  =>  {
    if  (observer.current)  observer.current.disconnect();

    observer.current  =  new  IntersectionObserver(handler,  options);
    for  (const  node  of  refs.current)  {
        observer.current.observe(node);
    }
    return  ()  =>  observer.current.disconnect();
},  []);

It's important to wrap it in a useEffect to make sure it will only be rendered JUST after the component is mounted. Otherwise, you won't have the refs. The first thing I do inside is to check if I have already an observer. In the case of true, then I use the disconnect method. This method lets me 'unobserve' all elements we were observing. So this is a kind of 'reset' to start again and observe again, in case we already had an observer.

Afterward, we create the observer with a handler and options, and we iterate all those refs to be observed. Notice that I return a method to make sure that I disconnect as well when this component is unmounted. If you are confused returning a method inside a use effect, check this article from React docs.

Let me show you my handler and options:

const  handler  =  (
    entries:  IntersectionObserverEntry[],
    observer:  IntersectionObserver
)  =>  {

    for  (const  entry  of  entries)  {
        if  (entry.intersectionRatio  >=  1)  {
            console.log("i Am visible",  entry.target.textContent);
        }
    }
};

const  options  =  {
    root:  null,
    rootMargin:  "0px",
    threshold:  1.0
};

And with that.... MAGIC, we got it! Together, dear reader, we achieved the goal I set at the beginning of this section!

But wait... there's a couple of gotchas and refactoring to do. Checking the react docs we find the following FAQ. It seems our intersection observer is creating it every time we re-render, and we don't want that. So we can refactor it to create the ref as a lazy load. The following snippet is just with the necessary changes to achieve it:

const  getObserver  =  (ref:  React.MutableRefObject<IntersectionObserver  |  null>)  =>  {
    let  observer  =  ref.current;
    if  (observer  !==  null)  {
        return  observer;
    }
    let  newObserver  =  new  IntersectionObserver(handler,  options);
    ref.current  =  newObserver;
    return  newObserver;
};

const  CarouselScroller:  React.FC<{}>  =  ()  =>  {
    const  observer  =  React.useRef<IntersectionObserver>(null);
    React.useEffect(()  =>  {
        if  (observer.current)  observer.current.disconnect();
        const  newObserver  =  getObserver(observer);

        for  (const  node  of  refs.current)  {
            newObserver.observe(node);
        }
        return  ()  =>  newObserver.disconnect();
    },  []);
    return (...)
}

I presented const observer = React.useRef<IntersectionObserver>(null); but when I was doing some playgrounds, I did const observer = React.useRef<IntersectionObserver>(new IntersectionObserver(handler,options));. That it's causing a new object every render, and therefore some performance errors.

Another gotcha well pointed coming from @aytee17 is that, for every render, we'll call the ref callback in the return method, and it will start to increase dramatically my array of references. The ref callback is being triggered twice: once when it's mounted into the DOM, and another when it's being removed from the DOM( it calls the callback, but the ref holds as null value instead of the HTML element). In short words: My first render my array will have 5 elements ( 5 sections that I add in this example), if I force a re-render, I will have 15 elements:

5 HTML elements from my first render and added into the DOM
5 nulls from when the elements were removed from the DOM
5 elements from the new re-render that are added into the DOM

So, my proposal, it's to wrap the addNode method into a useCallback. If you are wondering what it does, here I tried to explain it with my own words.

My final result:

import  *  as  React  from  "react";
import  {  Section,  LightSection,  Container  }  from  "./App.styled";

const  handler  =  (
    entries:  IntersectionObserverEntry[],
    observer:  IntersectionObserver
)  =>  {
    for  (const  entry  of  entries)  {
        if  (entry.intersectionRatio  >=  1)  {
            console.log("i Am visible",  entry.target.textContent);
        }
    }
};

const  options  =  {
    root:  null,
    rootMargin:  "0px",
    threshold:  1.0
};

const  getObserver  =  (ref:  React.MutableRefObject<IntersectionObserver  |  null>)  =>  {
    let  observer  =  ref.current;
    if  (observer  !==  null)  {
        return  observer;
    }
    let  newObserver  =  new  IntersectionObserver(handler,  options);
    ref.current  =  newObserver;
    return  newObserver;
};

const  CarouselScroller:  React.FC<{}>  =  ()  =>  {
    const  [count, setCount] =  React.useState(0);
    const  refs  =  React.useRef<HTMLDivElement[]>([]);
    const  observer  =  React.useRef<IntersectionObserver>(null);
    const  addNode  =  React.useCallback(
        (node:  HTMLDivElement)  =>  refs.current.push(node)
    ,[]);
    // ref callback is called twice: once when the DOM
    //node is created, and once (with null) when the DOM
    //node is removed.
    // TRY IT OUT => Comment the other addNode and uncomment this one
    //const addNode = (node: HTMLDivElement) => refs.current.push(node);

    React.useEffect(()  =>  {
        if  (observer.current)  observer.current.disconnect();
        const  newObserver  =  getObserver(observer);

        for  (const  node  of  refs.current)  {
            newObserver.observe(node);
        }
        return  ()  =>  newObserver.disconnect();
    },  []);

    console.log("render",  refs);
    return  (
        <React.Fragment>
            <Container>
                <Section  ref={addNode} color="#134611">
                    Section 1
                </Section>
                <Section  ref={addNode} color="#3E8914">
                    Section 2
                </Section>
                <Section  ref={addNode} color="#3DA35D">
                    Section 3
                </Section>
                <LightSection  ref={addNode} color="#96E072">
                    Section 4
                </LightSection>
                <LightSection  ref={addNode} color="#E8FCCF">
                    Section 5
                </LightSection>
            </Container>
            <button  onClick={() =>  setCount(count + 1)}> Re-render</button>
        </React.Fragment>
    );
};



CarouselScroller.displayName  =  "CarouselScroller";

export  default  CarouselScroller;

I added a useState to force a re-render. I added as well comment and a proposal, so you can see by yourself the problem to not wrap the method with useCallback

Check the code working in Sandbox

It's been an exciting journey to feel more confident with IntersectionObserver, and to document all my steps and how it helped me be more confident with it. My next steps are to generate these effects with real products and start and apply them to my job.

Code is just code, you won't harm anyone. So don't be afraid to go and understand the abstraction. If something is not clear, don't be afraid to ask the internet how to tackle it, and I encourage you to document it and explain it as well.

References for this post

Practical CSS SCroll Snapping

Well-Controlled Scrolling with CSS Scroll Snap

How to do scroll-linked animations the right way

Creating a RevealJS clone with CSS Scroll Snap Points

Intersection Observer: Track elements Scrolling Into View

How To Use an IntersectionObserver in a React Hook

See the original post at my blog suetBabySuet

How to use React context

Ruben Suet — Sat, 02 May 2020 10:52:14 +0000

It's been almost 7 years since the first version of React was released, and it is still one of the most popular libraries at the moment you want to work regarding frontend. The switch into JSX syntactic sugar, suspend, hooks, memo ( or the introduction of the pure component), all of them have been involved since that first released version of 23th May of 2013. One of the great points of React is its way to manage a state or pass state through different components, and definitely, that one has been evolving as well. There are different ways to tackle the state in a React application, and that's what I would like to explain in this post. I will separate it in 2 parts: 1) What is React context 2) Which option to pick as state management.

What Is React Context

One technique that I like currently is to use the native React context solution for state management. That I like this idea does not mean that I am just picking this one as a unique option in my day a day, I will explain it later.

From React docs:

Context provides a way to pass data through the component tree without
having to pass props down manually at every level.

It's as easy as it sounds: Pass data through components, avoiding the prop drilling. Some people consider prop drilling as an anti-pattern. I always think: that decision depends on the context (hopefully you got this bad joke, hehe). Jokes apart, I do not think of it as an anti-pattern. It seriously depends on the context, like the size of your app, how much scalable do you need it, how maintainable you want to do it, or is just going to be a one time coded app that rarely is going to be used? Here it's a good explanation from Kent C. Dodds regarding Prop drilling.

Let's assume we are working on an auth app, and we do not want to pass data through. We decided that our bundle is quite important, and we want to keep it as light as possible, so no external library to control it, and this is our code

// User.js
import React from 'react'

function User(){
    return (
        <React.Fragment> Hi {user.firstName} </React.Fragment>
    )
}

This is our goal, now the question is: how do we get this user.firstName. Let's create our first React context for it. Keep in mind that if you are working with classes, it can be slightly different syntax. for that, check React docs.

Creating Context

Let's introduce the first picture of our Context and split it by parts

// UserContext.js
import React from 'react'

export const UserContext = React.createContext(undefined)

export function UserProvider() {
  const [user, setUser] = React.useState(undefined)

    const manageUser = {user, setUser}

    return (
        <UserContext.Provider value={manageUser}>
            { children }
        </UserContext.Provider>
    )
}

Let's break this code into pieces:

const UserContext = React.createContext(undefined) .
- needed for the creation of the context itself. You can pass a first value into the context. In this case I set undefined
const [user, setUser] = React.useState(undefined)
- Single hook for the user check hooks if you are not familiarized with it.
const manageUser = {user, setUser}
- For learning purposes, I show explicitly the object of the user. That could go directly into the provider
  - <UserContext.Provider value={manageUser}>
  - The context we previously set, now it's passed as a React component, notice that needs to be under .Provider to make it work. it accepts the value option, which is exactly the value you are going to pass to the children.

With that, you have a context created. Not so complicated at the end :)

Consuming context

Coming back to our original skeleton, now we can update it to make it working:

// User.js
import React from 'react'
import { UserContext, UserProvider } from './UserContext.js'
import { fetchUser } from './utils' // Let's pretend we got a method for fetching the info of the user

function UserWithContext(){
    const {user, setUser} = React.useContext(UserContext)

    React.useEffect(() => {
        const infoUser = fetchUser()
        setUser(infoUser)
    }, [])

    if (!user || !user.firstName) {
        return <React.Fragment> You are not logged in</React.Fragment>
    }

    return (
        <React.Fragment> Hi {user.firstName} </React.Fragment>
    )
}

function User(){
  return (
    <UserProvider>
      <UserWithContext />
    </UserProvider>
  )
}

Voila, now we can retrieve the user info or set the user easily from context. Notice how I renamed the component into UserWithContext, and the User component itself is returning the provider as a Wrapper. That is important in order to consume the context UserContext. Otherwise, it would return undefined as value.

Why did I rename the main one instead of the 'Wrapper'? Because when you import, you can go for User. I think to see <UserWithProvider /> it's not the best, because you are letting know to the user who consumens this component, that you have some wrappers there.Instead, I would expect tu plug it and do not know how is build internally, like<User />.

This example has been created for learning purposes you do not need all of this if you just need a single component to consume all this info. Imagine the scenario of

<User>
  <ManageAccount>
    <OverviewInfo />
    <ManageInfo />
    ...
  </ManageAccount>
</User>

Here you have deeper levels, and you need this info user. Here it comes the value, when it contains a children that has another children and so on...

Best Practices

As you notice, for consuming the context I need to import the UserContext, UserProvider and even user the React.useContext. It's not a problem but we always have to remember the useContext and import the UserContext itself, so they are always coupled together. We can simplify this process if we move everything into a custom hook. We could do the following

// UserContext.js
import React from 'react'

const UserContext = React.createContext(undefined)

export function UserProvider() {
    const [user, setUser] = React.useState({})

    const manageUser = {user, setUser}

    return (
        <UserContext.Provider value={manageUser}>
            { children }
        </UserContext.Provider>
    )
}

export function useUser() {
  const {user, setUser} = React.useContext(UserContext)

  if( !user || !setUser) {
      throw new Error ('Provider of User has no value')
  }

  return { user, setUser}
}

With this technique we get 2 benefits:

Now the components who consumes this hook does not have to know that it's necessary to wrap the useContext, so we decoupled and hide this abstraction. They can just get the benefit of our user by just doing a useUser() without knowing what is internally
We throw an error in case there no info on the user or the method setUser. Notice how I slightly modified the initial value of the useState, otherwise, since hooks are async, it would always trigger this error because of the initial undefined (it's up to you to decide what to show for the initial value). The benefit of throwing this error is pure agile: fail early and fix it quick. In my opinion, it's better to just fail here and know that something is not going on well than just passing not valid info and fail at some point in deeper components.

Another refactor we can do here:

// UserContext.js
import React from 'react'

const UserContext = React.createContext(undefined)
const SetUserContext = React.createContext(undefined)

export function UserProvider() {
    const [user, setUser] = React.useState({})

    return (
        <SetUserContext.Provider value={setUser}>
            <UserContext.Provider value={user}>
                { children }
            </UserContext.Provider>
        </SetUserContext.Provider>
    )
}

export function useUser() {
  const { user } = React.useContext(UserContext)

  if( !user ) {
      throw new Error ('Provider of User has no value')
  }

  return user
}

export function useSetUser() {
  const { setUser } = React.useContext(SetUserContext)

  if(!setUser) {
      throw new Error ('Provider of SetUser has no value')
  }

  return setUser
}

Notice that I have 2 contexts now with 2 custom hooks, and I use one for each of the user properties coming from useState ( the object, and the method). Why would I do that?

Think about this, every time this component is re-rendered, a new object identity will be created for both user and setUser at the moment it is sent to the children, causing a re-render on all children's components. That, in big applications, will cause performance issues. Mainly every re-render it's generating a new const manageUser = {user, setUser} otherwise. Remember that in javascript {} === {} // false comparing the same object with same properties will be detected as different objects, and here is the tricky part: because of {user, setUser} === {user, setUser} // false this will re-generate always a new const manageUser and will re-render all children. React is doing a deep comparison with objects if they are inside the useState.

Probably you are a bit confused here. The previous paragraph was just some theory, here the practical side: Adding 2 contexts and hooks, one per each, will solve the re-render problem. You isolate them. The first Provider, the method, is just that: a method. So it's quite unlikely that it will ever change. The second Provider, the user object, is more likely to be changed, and that's why it goes in the second position: It will trigger a re-render on the children for the user, but never a re-render because of the method. If the position would be

  <UserContext.Provider value={user}>
    <SetUserContext.Provider value={setUser}>
      { children }
    </SetUserContext.Provider>
  </UserContext.Provider>

then every time the user is changed, it would be triggered setUser as well. Since that's a method, and we are not interested in re-render just a method that will never change, we put 'static' content in the top and the content that it's about to be changed more close to the children

I will talk in the future regarding object equality and probably this topic can be clearer because it's not easy to understand it.

My last refactor lies in the following

Context, Props drilling, Redux, Mobx, Xstate, Apollo Link... What to use?

There are several options to manage your state. I just presented one that I like, but that doesn't mean it needs to be the one and unique to follow. Every library or technique has its pros and cons, and it's up to you to decide at which moment you need one.

Let's cluster them from global state vs local state

Global state

So you configure at the very top of your app, probably <App /> component, this library you want to implement, so you can share info with all the components.

In my eyes, this can be a valid solution when you need to share some critical info with all the components ( maybe the user we talked before needs to be recognized in all components and it would be the better host as a global state). I assume you pick one solution ( it's on you to have Xstate and mobx and redux in your app, but it's hard to know where to pick the info for every library).

I would never use this solution in case I need to share the info to just 2 or 3 components that are going nested. Or even if they are not, consider the price to have a helper function that provides you this info VS having it in a global state from the first instance.

Clear example. I fetch info in one component, add a loading state in redux ( for example) to check in the nested component if it's loading. In case it is, I will show a spinner. This scenario, in my opinion, is a no go for a global solution. The complexity you had to add to just know if it's loading or not, wasn't paid off.

If you have an App that has I18N and depending on the language, you are fetching info from some headless CMS, and the language determines one endpoint or another, then I see it as a valid solution. So a lot of components need to know the language. Therefore, they can fetch with one token or another to the headless cms provider for dynamic info.

Local state

I would cluster local state as mainly native solutions from React as prop drilling or Context ( if there are some libraries based on local state management, let me know because I have no idea if there's any).

Prop drilling is great, you can go far just with that. It's the simplest and straightforward solution. If I have a component that is just nesting 2 or 3 more components, definitely I would go for this solution. One example: the container/component solution: I used to put the business logic in the container, and move the rendering and methods to help to render into the component. I would never think about something different than prop drilling approach. Just pass info from one component to another.

React context is great in the scenario that you have multiples components, all of them somehow connected into the same parent component. That can be dramatically misused as a global state, so please keep in mind you can have at the end as many contexts as possible in your app, try always to encapsulate them and make them as smaller as possible for your use cases. One example: I've been working in a Carousel at work. I have all the business logic in a container, then. I move into component, and the component has the content of the current slide to be shown, but as well some buttons for navigation, and arrows for navigation. We are easily talking around 6 components, all of them connected by the Carousel Container. I give as a valid here the cost to create a context

Last comments to keep in mind

Every solution always comes with a cost of effort and time. Cheapest solutions are easy to implement but not scalable and maintainable. Expensive solutions are scalable, can be hard to maintain as well, and needs a lot of time and effort. And here is my most important message: Always think for the use case you need what's the best approach in relation effort/cost. Pick the one that can work better for you at that specific moment and just that specific moment. Don't try to guess the future of that file in 6 months, because you'll never know.

Things I keep in mind to choose an approach:

Small apps don't need global state( they can have it, but there's a high chance of possibilities that you can live without)
If your app is big, it will help to have some global state.
How many people are working on this project? If it's just you, it's not a necessary global state. However, if there's an app with 20 people working under different domains ( imagine an E-shop: Checkout VS My Account), then probably you need to share some global info
How much needs to be scalable the component you need to work. If you know that's going to be a small component, stick with prop drilling
How much maintainability does it need? Try to remember that maybe you come into that file after 1 year that no one touched it. How can you make your life easy and be able to understand what's going on in the easiest and fastest way possible.

I hope this post helps you to understand the Context and which approach to take. If you want to talk with me, let's connect on twitter.

See the original post at my blog suetBabySuet